Image Tags, Digests, Mutable vs Immutable References, Pull Policies, Pinning, and Reproducibility: Concepts, Architecture, and Mental Model

1. The problem: the same tag can name different bytes tomorrow

A deployment file that says example/app:stable looks precise, but stable is only a registry tag. A publisher can move that tag from release A to release B without changing the text in your deployment file. If one host already has A cached and another host resolves the registry after the move, the two hosts can run different content while both report the same human-friendly tag.

This is not a Docker bug. Mutable aliases are useful for channels such as stable, 3.4, or nightly. The engineering mistake is treating the alias as immutable evidence. A reliable release process records the digest resolved at the moment of promotion and carries that identity forward with tests, scans, attestations, and deployment records.

2. Mental model: name → resolution → immutable object → platform content

flowchart TD
  A[repository:tag\nhuman-friendly mutable name] --> B[registry tag resolution]
  B --> C{single or multi-platform?}
  C -->|multi-platform| D[OCI image index\nimmutable digest]
  D --> E[platform manifest\nlinux/amd64 digest]
  D --> F[platform manifest\nlinux/arm64 digest]
  C -->|single-platform| E
  E --> G[config digest + layer digests]
  G --> H[local image object / image ID]
  H --> I[container created from exact local image]
            

The top-level digest may identify an image index. That index can point to several platform-specific manifest digests. A local image ID commonly corresponds to the config object identity for the selected local image. These values can all start with sha256: and still identify different objects.

3. Identity vocabulary: do not collapse these fields

4. Tags are pointers, not content hashes

Adding another tag to a local image does not duplicate its layers. It creates another name for the same local image object. Pushing a tag asks the registry to associate that name with a manifest or index. Pushing different content under the same tag later changes the tag’s resolution.

docker image tag chapter13-a:local example/app:1.0.0
docker image tag chapter13-a:local example/app:stable
docker image inspect chapter13-a:local --format '{{.Id}}'
docker image inspect example/app:stable --format '{{.Id}}'

If both aliases resolve to the same local object, the IDs match. That proves local aliasing only. It does not prove what a remote registry currently returns for either tag.

5. Digest identity and the multi-platform wrinkle

A digest is computed from the serialized content of the object it names. Changing that object changes its digest. For a multi-platform release, the tag commonly points to an image index. The index has one digest; its amd64 and arm64 child manifests have different digests. Therefore, an evidence record should state whether it captured the index digest, a platform manifest digest, or both.

Use registry-aware inspection when the distinction matters:

docker buildx imagetools inspect busybox:1.37.0
docker buildx imagetools inspect busybox:1.37.0 --format '{{.Name}}'

Do not copy a digest from one platform field and describe it as the identity of the entire multi-platform release unless the object being identified is actually the index.

6. Local image ID versus registry digest

The Engine can have a local image before it has ever been pushed, so a local image ID exists without a repository digest. After a successful pull or push, RepoDigests can associate local content with repository-qualified immutable identities. Those are different pieces of evidence.

docker image inspect busybox:1.37.0 \
  --format 'ID={{.Id}} RepoDigests={{json .RepoDigests}}'

7. Pull policy changes lookup behavior, not digest immutability

For docker run, --pull=missing is the default, --pull=always performs a registry pull before container creation, and --pull=never forbids an implicit pull. With a floating tag, this determines whether a cached local resolution can be reused. With a digest reference, the identity is already fixed; pulling may fetch missing content, but it cannot silently substitute different content under the same digest.

docker run --rm --pull=missing busybox:1.37.0 true
docker run --rm --pull=always busybox:1.37.0 true
docker run --rm --pull=never busybox:1.37.0 true

Compose has a broader policy surface, including time-based checks. Treat the policy as a freshness/lookup rule, not as artifact identity.

8. Build once, promote the same digest

A release pipeline should bind source revision, build inputs, builder/toolchain, tests, scan/attestation results, and the resulting registry digest. Promotion then attaches an environment-facing alias or deployment reference to that already-tested digest. Rebuilding “the same version” for staging and production creates new bytes and breaks the evidence chain even if the tag text is unchanged.

9. Read-only inspection before changing anything

docker version
docker context show
docker image ls --digests
docker image inspect IMAGE --format \
'ID={{.Id}} RepoTags={{json .RepoTags}} RepoDigests={{json .RepoDigests}} OS={{.Os}} Arch={{.Architecture}}'
docker inspect CONTAINER --format \
'Container={{.Id}} LocalImageID={{.Image}} RequestedImage={{.Config.Image}}'

Capture these fields before pulling, retagging, recreating, or deleting anything during an incident. A later successful pull can erase the evidence that the host had stale content.

10. Common misconceptions

• “latest means newest.” It is only a conventional tag name.
• “A semantic version tag cannot move.” Registries generally allow it unless policy prevents it.
• “The image ID is the registry digest.” They identify different objects/contexts.
• “Pinned means automatically secure forever.” Pinning freezes bytes; you still need controlled updates when better base images or fixes appear.
• “Always pull means reproducible.” With a mutable tag, always-pull intentionally asks the registry for the tag’s current meaning.

Knowledge check

Official references and version notes

• docker image ls — digest display, local image IDs, and digest-addressed pull/create/run examples.
• docker image inspect — low-level local image metadata, including platform-aware inspection on capable stores.
• docker run — current --pull=missing|always|never semantics.
• Compose pull_policy — always, never, missing, build, daily, weekly, and every_<duration>.
• Docker build best practices — pinning base images by digest, controlled updates, and auditability tradeoffs.
• docker buildx imagetools inspect — registry-side manifest/index and platform inspection.
• Image digests — manifest-list/index versus per-platform image digest distinctions.
• OCI Image Index Specification — immutable index descriptors and platform selection.
• OCI Image Manifest Specification — config and layer descriptors addressed by digest.
• Docker Engine 29 release notes — Engine 29.8.1 baseline used when authoring this chapter.
• Buildx releases and BuildKit releases — current build-tool release history.