When a Docker image is specified with both a version tag and a digest, Docker uses the digest to determine which image to pull and ignores the version tag completely. This creates misleading documentation, as the version tag may not reflect the actual image version being used.
This creates confusion during code review, debugging, and maintenance. Developers reading the Dockerfile will see the version tag and assume that version is being used, when Docker actually ignores it and uses the image specified by the digest instead.
To avoid this issue, it is recommended to specify either the version tag or the digest of the image. For example, instead of
my-image:1.2.3@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d, it is better to use my-image:1.2.3
or my-image@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d.
For even more control and traceability, the digest can be used instead of the version tag. This will pin the image to a specific immutable version,
ensuring reproducible builds, but will also prevent automatic security updates that would come from using a version tag. An example would be
my-image@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d.
Additional information can be found in the Resources section below. See also a related rule {rule:docker:S7023}.
FROM my-image:1.2.3@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d
FROM my-image:1.2.3
or:
FROM my-image@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d
This way, the version of the Docker image is pulled using either the digest or the version tag, ensuring that the specified version information accurately represents the image that will be pulled.
Additionally, when only the digest is specified, a comment can be added to specify the version of the image to improve readability. For example,
# my-image-1.2.3 FROM my-image@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d