Skip to content

pin-service-image

Compose services with an untagged or :latest image deploy a different container every pull. How to pin service images to a tag or digest.

On this page

image: nginx and image: redis:latest both mean "whatever the registry serves today". In a Compose file that's worse than in a Dockerfile, because the file is the deployment: two hosts running the same file can silently run different software, and so can one host after a reboot pulls fresh. This rule flags service images with no tag or with the mutable latest tag. Services built from a local build: context are skipped, as are ${VAR}-templated references.

What the rule catches

compose.yaml — images that mean something different every pull
services:
  web:
    image: nginx
  cache:
    image: redis:latest

Scanning this file reports:

⚠ WARN [docker-doctor/pin-service-image]
  Service 'web' image 'nginx' does not specify a tag. Every pull may fetch a different image.

Why it matters

Unpinned images break the two properties a deployment file exists to provide. Reproducibility: "works on staging" means nothing if production pulled a different latest an hour later. Rollback: re-deploying yesterday's compose file after a bad release still pulls today's image, so the rollback undoes nothing. Pinning makes the file's git history an accurate record of what actually ran, which is also what an incident review needs.

How to fix it

Pin the image to a specific tag or digest (e.g. nginx:1.27-alpine) so deploys are reproducible and a rollback actually rolls back.

compose.yaml — every host resolves the same image
services:
  web:
    image: nginx:1.27-alpine
  cache:
    image: redis:7.4-alpine

A version tag (nginx:1.27-alpine) is the practical default: readable, and mutated rarely enough for most services. For supply-chain-sensitive deployments, pin the digest (nginx:1.27-alpine@sha256:…). A digest is immutable by construction, and the tag next to it stays as documentation. Renovate and Dependabot both understand Compose files, so pinned versions don't have to mean stale versions. The same reasoning for Dockerfile base images lives in pin-image-version.

Rule details

  • Rule key — docker-doctor/pin-service-image
  • Category — Compose
  • Default severity — warning
  • Applies to — Docker Compose files

Explain this rule from the CLI:

npx @docker-doctor/cli@latest rules explain docker-doctor/pin-service-image

Change its severity — or turn it off — in your config file:

// docker-doctor.config.ts
export default {
  rules: {
    "docker-doctor/pin-service-image": "off",
  },
};

Severity affects the health score: error findings cost more points than warning, and info costs the least.