19.1.3.2 Pull Tag Selection

Pull tag selection is the deliberate decision of exactly which tag variant to pull for a given purpose, choosing between a floating major-version tag and a fully pinned patch version, selecting the right variant suffix among several published options, and choosing an appropriate reference specifically when pulling for cache-warming purposes rather than for the actual, final deployment.

Floating versus fully pinned version tags

Most widely published base images offer several levels of version specificity simultaneously, a floating major-version tag that continues receiving updates, and increasingly specific, fully pinned patch-version tags that never change once published:

docker pull node:20
docker pull node:20.11
docker pull node:20.11.0

For local development, where automatically picking up routine patch updates is often genuinely convenient, the floating major-version tag is a reasonable choice; for anything feeding into a reproducible build pipeline, the fully pinned patch version is the more appropriate choice, following the same reproducibility reasoning covered in dedicated pinning content generally.

Choosing among published variant suffixes

Many images publish several distinct variants under different tag suffixes, full, slim, alpine, distroless, each representing a different point on the size-versus-compatibility spectrum covered in dedicated minimal base content, and selecting the right one for a given pull depends on the actual, specific need:

docker pull node:20
docker pull node:20-slim
docker pull node:20-alpine

Pulling the full variant for a quick, exploratory local test where compatibility convenience matters more than size is reasonable; pulling the alpine variant for a production build where minimizing final image size matters considerably more is the more deliberate, appropriate choice for that specific, different purpose.

Selecting a tag specifically for CI cache warming

When pulling an image purely to warm a CI runner's local cache ahead of an actual build, pulling the previous, known-good tag (rather than the exact tag the upcoming build will eventually produce, which does not exist yet) provides the most relevant cached layers for the subsequent build to actually benefit from:

docker pull registry.example.com/my-api:1.4.1 || true
docker build --cache-from registry.example.com/my-api:1.4.1 -t my-api:1.4.2 .

The || true here tolerates a pull failure gracefully, since this cache-warming pull is an optimization, not a strict requirement, and a build should still proceed correctly even if no previous cached image happens to be available to pull as a cache source.

Pulling a digest-specific reference for verification purposes

When the actual goal is verifying a specific, exact piece of content rather than retrieving whatever a tag currently happens to point to, pulling by digest explicitly removes any ambiguity about exactly what was retrieved:

docker pull my-api@sha256:3f29a8c1d8e2b4f6a9c7d5e8b1f3a6c9d2e5f8b1a4c7d0e3f6a9c2d5e8b1f4a7

This is the appropriate choice specifically for a verification or audit scenario, confirming exactly what content a previously recorded digest reference actually corresponds to, distinct from an ordinary development or build pull where a tag is generally the more convenient, appropriate reference to use instead.

Selecting a tag matching the target deployment environment

For an image with separate tags targeting different runtime environments or configurations, debug-enabled, production-optimized, choosing the tag matching the actual intended deployment context, rather than defaulting to whichever tag happens to be most familiar or convenient, avoids inadvertently deploying a debug-oriented variant where a production-optimized one was actually needed:

docker pull my-api:1.4.2-debug
docker pull my-api:1.4.2

Confirming a project's own tag naming convention directly, rather than assuming based on a different project's different convention, avoids this kind of mismatch when working across multiple projects with potentially different tagging practices.

Common mistakes

• Pulling a floating major-version tag for a build pipeline genuinely needing reproducibility, rather than a fully pinned, specific patch version.
• Choosing a full, larger base image variant for a production build where a more minimal variant would have been the more deliberate, appropriate choice.
• Attempting to pull the exact tag a build is about to produce as its own cache source, when that tag does not exist yet and the previous, already-published tag is the actually useful reference for this purpose.
• Using an ordinary tag reference where a genuine, exact digest pull was actually needed for a verification or audit-specific purpose.
• Defaulting to a familiar tag naming convention from a different project without confirming the current project's own, potentially different tagging convention for debug versus production variants.

Pull tag selection is a deliberate decision matched to the actual purpose of a given pull, floating versus pinned for development versus reproducible builds, variant suffix selection based on the size-versus-compatibility need, the previous tag specifically for cache warming, and digest references specifically for verification, rather than defaulting reflexively to whichever tag happens to be most familiar regardless of the actual context.