Skip to content

Fix DockerImageName compatibility check when digest is present #11629

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
konstantinosGkilas wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Fix DockerImageName compatibility check when digest is present #11629

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6c576a5
Fix DockerImageName compatibility check when digest is present (#10527)
konstantinosGkilas Apr 2, 2026
6da85e7
Preserve tag in DockerImageName when both tag and digest are present
konstantinosGkilas Apr 3, 2026
a63de7c
Fix malformed tag parsing and equals/hashCode for tag+digest images
konstantinosGkilas Apr 4, 2026
3651ae9
Merge branch 'main' into feature/10527-dockerimagename-digest-compati…
konstantinosGkilas Apr 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion core/src/main/java/org/testcontainers/images/RemoteDockerImage.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,9 +89,10 @@ protected final String resolve() {
final Instant startedAt = Instant.now();
final Instant lastRetryAllowed = Instant.now().plus(PULL_RETRY_TIME_LIMIT);
final AtomicReference<Exception> lastFailure = new AtomicReference<>();
String pullTag = imageName.getDigest() != null ? imageName.getDigest() : imageName.getVersionPart();
final PullImageCmd pullImageCmd = dockerClient
.pullImageCmd(imageName.getUnversionedPart())
.withTag(imageName.getVersionPart());
.withTag(pullTag);
final AtomicReference<String> dockerImageName = new AtomicReference<>();

// The following poll interval in ms: 50, 100, 200, 400, 800....
Expand Down
37 changes: 34 additions & 3 deletions core/src/main/java/org/testcontainers/utility/DockerImageName.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,8 +87,15 @@ public DockerImageName(String fullImageName) {
}

if (remoteName.contains("@sha256:")) {
repository = remoteName.split("@sha256:")[0];
versioning = new Sha256Versioning(remoteName.split("@sha256:")[1]);
String beforeDigest = remoteName.split("@sha256:")[0];
if (beforeDigest.contains(":")) {
repository = beforeDigest.split(":")[0];
String tag = beforeDigest.split(":", 2)[1];
versioning = new Sha256Versioning(remoteName.split("@sha256:")[1], tag);
} else {
repository = beforeDigest;
versioning = new Sha256Versioning(remoteName.split("@sha256:")[1]);
}
} else if (remoteName.contains(":")) {
repository = remoteName.split(":")[0];
versioning = new TagVersioning(remoteName.split(":")[1]);
Expand Down Expand Up @@ -155,16 +162,40 @@ public String getUnversionedPart() {
}

/**
* @return the versioned part of this name (tag or sha256)
* @return the versioned part of this name (tag or sha256). When both tag and digest are present,
* the tag is returned.
Comment on lines +165 to +166
Copy link
Copy Markdown

@burneyy burneyy Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this mean that the tag has a higher priority than the digest? If yes, I think that is not a good idea, because version tags are mutable and can suddenly point to another build. In contrast, digests are immutable and will always point to the exact same build. In light of recent supply chain attacks, preferring digests over tags is of particular importance.

Copy link
Copy Markdown
Author

@konstantinosGkilas konstantinosGkilas Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @burneyy , great point on supply chain security — and you're right that tags are mutable while digests are immutable.

However, getVersionPart() returning the tag is intentional here. It's used exclusively for version-based compatibility checks in modules like KafkaContainer, ElasticsearchContainer, Neo4jContainer, etc., where a human-readable version string (e.g. 7.3.0) is needed for version comparisons.

The actual image pulling in RemoteDockerImage already prefers the digest:

String pullTag = imageName.getDigest() != null ? imageName.getDigest() : imageName.getVersionPart();

So when both tag and digest are present, the image is always pulled by its immutable digest — the tag is never used for pulling. The security concern is therefore already handled.

Copy link
Copy Markdown

@burneyy burneyy Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @konstantinosGkilas,
I see, apologies for the noise then and thanks for the explanation! Happy to hear that the digest is preferred over the version tag when performing the actual pulling already. Thanks for taking care of this issue - much appreciated 🙏

*/
public String getVersionPart() {
if (versioning instanceof Sha256Versioning) {
String tag = ((Sha256Versioning) versioning).getTag();
if (tag != null) {
return tag;
}
}
return versioning.toString();
}

/**
* @return the sha256 digest if present, or null
*/
@Nullable
public String getDigest() {
if (versioning instanceof Sha256Versioning) {
return versioning.toString();
}
return null;
}

/**
* @return canonical name for the image
*/
public String asCanonicalNameString() {
if (versioning instanceof Sha256Versioning) {
String tag = ((Sha256Versioning) versioning).getTag();
if (tag != null) {
return getUnversionedPart() + ":" + tag + "@" + versioning;
}
}
return getUnversionedPart() + versioning.getSeparator() + getVersionPart();
}

Expand Down
14 changes: 14 additions & 0 deletions core/src/main/java/org/testcontainers/utility/Versioning.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,12 +79,26 @@ class Sha256Versioning implements Versioning {

private final String hash;

private final String tag;

Sha256Versioning(String hash) {
this(hash, null);
}

Sha256Versioning(String hash, String tag) {
this.hash = hash;
this.tag = tag;
}
Comment on lines +88 to +91
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot Apr 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Validate tag syntax for tag+digest inputs

After introducing the optional tag field on Sha256Versioning, DockerImageName.parse("name:tag@sha256:...") now stores the tag there, but Sha256Versioning.isValid() still validates only the hash. This means malformed tags (for example name:-bad@sha256:...) can pass assertValid(), which is a regression in image-name validation and can defer failures to later pull operations.

Useful? React with 👍 / 👎.


String getTag() {
return tag;
}

@Override
public boolean isValid() {
if (tag != null && !tag.matches(TagVersioning.TAG_REGEX)) {
return false;
}
return hash.matches(HASH_REGEX);
}

Expand Down
29 changes: 29 additions & 0 deletions core/src/test/java/org/testcontainers/utility/DockerImageNameCompatibilityTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,35 @@ void testImageWithClaimedCompatibilityForVersion() {
.isFalse();
}

@Test
void testDigestOnlyImageIsCompatible() {
DockerImageName subject = DockerImageName.parse("postgres@sha256:1234abcd1234abcd1234abcd1234abcd");

assertThat(subject.isCompatibleWith(DockerImageName.parse("postgres")))
.as("postgres@sha256:... ~= postgres")
.isTrue();
}

@Test
void testTagAndDigestImageIsCompatible() {
DockerImageName subject = DockerImageName.parse("postgres:16.8@sha256:1234abcd1234abcd1234abcd1234abcd");

assertThat(subject.isCompatibleWith(DockerImageName.parse("postgres")))
.as("postgres:16.8@sha256:... ~= postgres")
.isTrue();
}

@Test
void testTagAndDigestImageWithRegistryIsCompatible() {
DockerImageName subject = DockerImageName.parse(
"registry.foo.com/repo:tag@sha256:1234abcd1234abcd1234abcd1234abcd"
);

assertThat(subject.isCompatibleWith(DockerImageName.parse("registry.foo.com/repo")))
.as("registry.foo.com/repo:tag@sha256:... ~= registry.foo.com/repo")
.isTrue();
}

@Test
void testAssertMethodAcceptsCompatible() {
DockerImageName subject = DockerImageName.parse("foo").asCompatibleSubstituteFor("bar");
Expand Down
71 changes: 71 additions & 0 deletions core/src/test/java/org/testcontainers/utility/DockerImageNameTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package org.testcontainers.utility;

import org.junit.jupiter.api.Nested;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.Arguments;
import org.junit.jupiter.params.provider.MethodSource;
Expand All @@ -24,6 +25,8 @@ public static String[] getNames() {
"registry.foo.com:1234/repo_here/my-name:1.0",
"registry.foo.com:1234/repo-here/my-name@sha256:1234abcd1234abcd1234abcd1234abcd",
"registry.foo.com:1234/my-name@sha256:1234abcd1234abcd1234abcd1234abcd",
"myname:latest@sha256:1234abcd1234abcd1234abcd1234abcd",
"registry.foo.com:1234/repo-here/my-name:1.0@sha256:1234abcd1234abcd1234abcd1234abcd",
"1.2.3.4/my-name:1.0",
"1.2.3.4:1234/my-name:1.0",
"1.2.3.4/repo-here/my-name:1.0",
Expand Down Expand Up @@ -147,4 +150,72 @@ void testParsing(
}
}
}

@Nested
class TagAndDigestParsing {

@Test
void testTagAndDigestStripsTagFromRepository() {
DockerImageName imageName = DockerImageName.parse("myname:latest@sha256:1234abcd1234abcd1234abcd1234abcd");

assertThat(imageName.getRegistry()).isEqualTo("");
assertThat(imageName.getUnversionedPart()).isEqualTo("myname");
assertThat(imageName.getVersionPart()).isEqualTo("latest");
assertThat(imageName.getDigest()).isEqualTo("sha256:1234abcd1234abcd1234abcd1234abcd");
assertThat(imageName.asCanonicalNameString())
.isEqualTo("myname:latest@sha256:1234abcd1234abcd1234abcd1234abcd");
}

@Test
void testTagAndDigestWithRepoPath() {
DockerImageName imageName = DockerImageName.parse(
"repo/myname:1.0@sha256:1234abcd1234abcd1234abcd1234abcd"
);

assertThat(imageName.getRegistry()).isEqualTo("");
assertThat(imageName.getUnversionedPart()).isEqualTo("repo/myname");
assertThat(imageName.getVersionPart()).isEqualTo("1.0");
assertThat(imageName.getDigest()).isEqualTo("sha256:1234abcd1234abcd1234abcd1234abcd");
assertThat(imageName.asCanonicalNameString())
.isEqualTo("repo/myname:1.0@sha256:1234abcd1234abcd1234abcd1234abcd");
}

@Test
void testTagAndDigestWithRegistry() {
DockerImageName imageName = DockerImageName.parse(
"registry.foo.com:1234/repo-here/my-name:1.0@sha256:1234abcd1234abcd1234abcd1234abcd"
);

assertThat(imageName.getRegistry()).isEqualTo("registry.foo.com:1234");
assertThat(imageName.getUnversionedPart()).isEqualTo("registry.foo.com:1234/repo-here/my-name");
assertThat(imageName.getVersionPart()).isEqualTo("1.0");
assertThat(imageName.getDigest()).isEqualTo("sha256:1234abcd1234abcd1234abcd1234abcd");
assertThat(imageName.asCanonicalNameString())
.isEqualTo("registry.foo.com:1234/repo-here/my-name:1.0@sha256:1234abcd1234abcd1234abcd1234abcd");
}

@Test
void testMalformedTagWithExtraColonIsRejected() {
assertThatThrownBy(() ->
DockerImageName.parse("repo/image:tag:extra@sha256:1234abcd1234abcd1234abcd1234abcd").assertValid()
)
.isInstanceOf(IllegalArgumentException.class);
}

@Test
void testDifferentTagsSameDigestAreNotEqual() {
DockerImageName a = DockerImageName.parse("repo/image:1.0@sha256:1234abcd1234abcd1234abcd1234abcd");
DockerImageName b = DockerImageName.parse("repo/image:latest@sha256:1234abcd1234abcd1234abcd1234abcd");

assertThat(a).isNotEqualTo(b);
}

@Test
void testDigestOnlyHasNoTag() {
DockerImageName imageName = DockerImageName.parse("myname@sha256:1234abcd1234abcd1234abcd1234abcd");

assertThat(imageName.getVersionPart()).isEqualTo("sha256:1234abcd1234abcd1234abcd1234abcd");
assertThat(imageName.getDigest()).isEqualTo("sha256:1234abcd1234abcd1234abcd1234abcd");
}
}
}