Container image tags versus digests: mutable names and content addresses

What it is

An OCI registry stores blobs (layers and manifests) by content address. The distribution specification (cited) defines a digest as a unique identifier created from a cryptographic hash of a blob's content and a tag as a custom, human-readable pointer to a manifest; a manifest digest may have zero, one or many tags referencing it. The image specification's descriptor section (cited) explains that the digest acts as a content identifier and that content fetched from an untrusted source can be verified by recalculating it. A reference therefore has two forms: registry/repo:tag resolves through a mutable pointer, while registry/repo@sha256:<hex> names bytes. The Docker CLI reference (cited) calls the second form pulling by an immutable identifier.

Why it matters

python:3.12-slim today and next month are different images with the same name; myapp:latest on two nodes can be two builds. A rollback "to the previous tag" may fetch something newer than what ran before if the tag was re-pushed. Vulnerability scans, provenance attestations and signatures all attach to digests, so a deployment described only by tag cannot be matched to its scan result. Conversely, a digest has no meaning to a human without a record of what it was built from.

How to apply

• Push a build once under an immutable identity (sha-<commit> or a version tag) and let CI print the resulting digest; store it with the release.
• Deploy by digest: image: registry/app@sha256:… in manifests, or resolve the tag to a digest at deploy time and record it in the rendered manifest.
• Pin base images in Dockerfiles as FROM image:tag@sha256:… so the tag documents intent and the digest fixes content; refresh both through reviewed update pull requests.
• Use floating tags (latest, 3.12) only for interactive use and for discovering what to pin next.
• Treat a multi-platform tag carefully: it points to an image index whose digest differs from the per-platform manifest digests inside it.

Pitfalls

Registry listings are usually organised by tag, so an untagged manifest is easy to overlook although it is still pullable by digest and still occupies storage. The distribution specification lets a registry implement tag deletion separately from manifest deletion, so removing a tag does not by itself free the manifest or its layers. Re-packaging an image (for example, re-compressing layers or rebuilding with different metadata) changes the digest even though the files inside are identical; signatures and attestations, by contrast, are stored beside the image and do not change it.