13.2.1.4 Immutable Image Promotion
A focused guide to Immutable Image Promotion, connecting core concepts with practical Docker and container operations.
Immutable image promotion refers to the practice of treating a specific image's content as fixed and unchanging once built, promoting that exact same content (referenced precisely, typically by digest or commit SHA) through each environment rather than allowing a tag's underlying content to silently change as it moves between stages.
Why Referencing by Digest Provides True Immutability
A tag alone (like a commit SHA tag) is conventionally treated as immutable, but a registry technically permits retagging — referencing an image by its content digest provides a guarantee that's enforced by the registry itself, not just by convention.
docker inspect registry.example.com/myapp:abc123 --format '{{.RepoDigests}}'
registry.example.com/myapp@sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Deploying using this digest-based reference guarantees the exact same image content is used, regardless of whether the more convenient SHA tag might have been altered to point elsewhere.
Promoting by Digest Through Each Environment
A digest-based promotion flow uses this precise reference at every stage, rather than relying on a tag that could theoretically be reassigned.
docker pull registry.example.com/myapp@sha256:e3b0c4429...
docker tag registry.example.com/myapp@sha256:e3b0c4429... registry.example.com/myapp:staging
Why This Matters Most for the Most Consequential Promotions
While day-to-day convenience often favors tag-based references, a production promotion specifically benefits from this stronger, digest-based guarantee, given how much is at stake in ensuring exactly the validated content is what's actually deployed.
docker pull registry.example.com/myapp@sha256:e3b0c4429...
docker compose up -d
Why Immutable Image Promotion Matters
Promoting by content digest, rather than relying solely on convention-based tag immutability, provides the strongest possible guarantee that what's deployed to each successive environment is precisely, verifiably the same content that was originally built and validated.