11.1.1.4 Digest Trust Pinning

Digest trust pinning references a base image by its exact content digest rather than a mutable tag, guaranteeing that a build always uses precisely the same, previously verified image content, immune to any later change in what a given tag happens to point to.

Pinning to a Specific Digest

A digest, rather than a tag, is referenced directly in the FROM instruction.

FROM node@sha256:a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2

This guarantees every build using this Dockerfile uses exactly this specific image content, regardless of any subsequent change to what the node:20-alpine tag (which this digest might currently correspond to) points to in the future.

Why This Matters for Reproducible, Auditable Builds

A build pinned to a specific digest produces a verifiably identical result every time it's run, since there's no possibility of the referenced content silently changing underneath it, unlike a build referencing a mutable tag.

FROM node:20-alpine

FROM node@sha256:a1b2c3d4e5f6...

The second form provides a stronger reproducibility and audit guarantee than the first, which could in principle resolve to different actual content depending on exactly when the build runs.

Finding an Image's Current Digest

The digest corresponding to a specific tag at a given point in time can be retrieved directly.

docker inspect --format='{{index .RepoDigests 0}}' node:20-alpine

Balancing Digest Pinning Against Receiving Security Updates

A digest-pinned image never automatically receives the security patches a tag would eventually pick up — deliberately, periodically updating the pinned digest to a newer, re-verified version is necessary to actually benefit from upstream security fixes over time.

docker pull node:20-alpine
docker inspect --format='{{index .RepoDigests 0}}' node:20-alpine

Periodically re-checking and updating the pinned digest keeps a digest-pinned build both reproducible and reasonably current with upstream security fixes.

Why Digest Trust Pinning Matters

Digest pinning provides the strongest possible guarantee against unexpected content changes in a referenced image, valuable for reproducibility and security auditing, while requiring a deliberate, periodic process to actually incorporate upstream updates over time.