How to Pin a Docker Base Image by Digest in CI

A tag like latest can change under you; a sha256 digest always resolves to the exact same image bytes.

Reference the base image as image@sha256:<digest> in the FROM line. Builds become reproducible and immune to a tag being repointed, which matters for supply-chain integrity in CI.

Steps

• Resolve the digest with docker buildx imagetools inspect <image>:<tag>.
• Replace the tag in FROM with @sha256:<digest>.
• Update digests deliberately (e.g. via Dependabot) rather than silently on every build.

Dockerfile

# Pinned: node:20-bookworm-slim resolved to an immutable digest
FROM node:20-bookworm-slim@sha256:0e07c9f6a8b8c0f4b1c0c9a2d3e4f5061728394a5b6c7d8e9f0a1b2c3d4e5f6a7
WORKDIR /app
COPY package*.json ./
RUN npm ci

Gotchas

• A digest pins one architecture unless it points at a manifest list; multi-arch builds should pin the list digest.
• Pinning freezes security patches too, so automate digest bumps to keep getting fixes.

Related guides