3.2.3.5 Digest Rollback Reference
A focused guide to Digest Rollback Reference, connecting core concepts with practical Docker and container operations.
A digest rollback reference uses a previously recorded content digest, rather than a version tag, to revert a deployment to an earlier state with absolute certainty about exactly which content is being restored, eliminating any ambiguity that could arise if a tag had since been reassigned.
Why a Digest Is the Most Reliable Rollback Target
If a tag used in a previous deployment has since been reassigned to different content, rolling back using that tag would not actually restore the original state — rolling back using the digest that was recorded at the time avoids this problem entirely, since a digest never changes meaning.
docker run -d registry.example.com/myapp@sha256:previousdigest...
This restores exactly the content that was running before, regardless of what any tag currently points to.
Maintaining a History of Deployed Digests
To make digest-based rollback practical, deployment systems typically need to record the digest deployed at each release, rather than only recording the tag that was used, since the tag alone may not be sufficient to reconstruct what was actually running later.
docker inspect registry.example.com/myapp:2.3.0 --format '{{index .RepoDigests 0}}' >> deployment-history.log
Rolling Back in an Orchestrated Environment
Orchestrators that track deployment history internally typically retain the specific digest of each previously deployed revision, which is what allows a rollback operation to restore precisely the prior state without relying on tags at all.
kubectl rollout history deployment/myapp
kubectl rollout undo deployment/myapp --to-revision=4
The orchestrator resolves this rollback to the exact image digest recorded for that revision, not to whatever a tag might currently point to.
Why Digest-Based Rollback Matters
Rollback is only as trustworthy as the reference it relies on — rolling back to "version 2.2.9" by tag carries residual risk if that tag was ever reassigned, while rolling back to a specific digest carries no such risk, since a digest, by construction, can only ever refer to one exact, unchanging set of content.