Image Tags, Digests, Mutable vs Immutable References, Pull Policies, Pinning, and Reproducibility: Configuration, Design Choices, and Tradeoffs

1. Start with the decision, not the syntax

The right reference strategy depends on what the consumer is trying to optimize. A developer may intentionally follow app:dev. A production rollback procedure needs an exact immutable identity. A Dockerfile base should usually be readable to humans but also reproducible enough to audit. These goals are not contradictory when you keep an alias and its digest together.

2. Reference strategy decision table

3. Docker Engine pull policies

docker run --pull=missing uses local cached content when the named image exists, always initiates a pull before container creation, and never requires the image to already be local. These policies answer “should I consult the registry?” They do not answer “which release is approved?”

4. Compose adds time-based and build-aware policies

Current Compose service configuration supports always, never, missing, build, daily, weekly, and every_<duration>. The latest tag is always pulled under missing. This is useful for developer freshness policies, but production identity should still be explicit.

services:
  api:
    image: registry.example/team/api@sha256:REVIEWED_DIGEST
    pull_policy: missing

Here the digest fixes identity; the policy controls whether missing content can be retrieved. Avoid inventing a tag-refresh policy as a substitute for release approval.

5. Base-image pinning: deterministic input versus automatic drift

Docker’s build guidance recommends digest pinning when you need exact base identity. A pattern such as FROM alpine:3.21@sha256:… communicates the intended release line and freezes the exact object. If the publisher later updates 3.21, your build does not silently change.

The cost is deliberate maintenance: a pinned base does not automatically absorb security fixes. Use dependency automation or scheduled review to propose a new digest, rerun tests/scans, and merge the update with an audit trail.

6. Build once; move references, not bytes

flowchart TD
  A[Source SHA] --> B[Build once]
  B --> C[Digest D]
  C --> D[Test / scan / attest D]
  D --> E[Attach candidate alias to D]
  E --> F[Promote staging alias to D]
  F --> G[Promote production alias to D]
  G --> H[Deployment records D]
            

If promotion rebuilds the source, the new result is a new artifact that requires its own evidence. A tag that says the same version does not make two builds identical.

7. Multi-platform promotion needs two levels of identity

For a multi-platform release, record the index digest as the release-set identity and retain the child manifest digests used by supported platforms. If an arm64-only incident occurs, the index proves the overall release while the arm64 descriptor identifies the exact failing platform artifact.

8. Worked scenarios

9. Registry policy can reinforce—but not replace—evidence

Some registries can protect tags from mutation. That is useful governance, but consumers should still record digests because the digest travels with scans, signatures, attestations, deployment records, and incident evidence. Registry policy answers “who may move this alias?”; the digest answers “what content is this?”

10. Decision challenge

Your CI pipeline pushes app:2.7.4, tests it, then rebuilds the same source in a production job and pushes the new bytes under the same tag. Explain why this breaks provenance even if both images pass tests, and redesign the workflow so staging and production consume the exact approved digest.

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.