Working with Image Digests Instead of Mutable Tags
Comparing mutable image tags vs content-addressable SHA-256 digests, eliminating tag drift, securing Kubernetes manifests, and automated digest pinning workflows.
Published on • November 18, 2026
AI Assistant

In Docker registries, image tags (such as :latest, :1.25, or :stable) are mutable pointers. Anyone with write access to a registry repository can overwrite a tag to point to a completely different image manifest at any time.
To achieve true immutability, zero-trust security, and bit-for-bit reproducible deployments, production systems use content-addressable image digests (SHA-256 hashes).
In this article, we will examine how image digests work, why mutable tags lead to production bugs, and how to automate digest pinning in Dockerfiles and Kubernetes manifests.
Understanding Image Digests vs Tags
+-----------------------------------------------------------------------------------+
| Mutable Tag Reference: nginx:1.25 |
| - Can be overwritten in registry tomorrow by maintainers |
| - May resolve to different layers on different host nodes |
+-----------------------------------------------------------------------------------+
| Content-Addressable Digest Reference: |
| nginx@sha256:4c0f3f20865ebd3757f40660bc9b7b038b69da3851ab424a2ae7f29feabcb285 |
| - Immutable cryptographic hash of the image manifest |
| - GUARANTEED to resolve to the exact same image binaries forever |
+-----------------------------------------------------------------------------------+
Every container image manifest uploaded to an OCI registry is hashed using SHA-256. This SHA-256 fingerprint is the image digest.
Unlike a tag (which is just a human-friendly alias), the digest changes if even a single byte inside any filesystem layer or configuration JSON changes.
Why Mutable Tags Cause Production Bugs
1. Tag Drift Across Cluster Nodes
Imagine a Kubernetes cluster with 5 worker nodes running a deployment specified as image: myapp:1.2.0.
- Node A pulled
myapp:1.2.0on Monday. - A hotfix was pushed to
myapp:1.2.0on Tuesday without bumping the version tag. - Node B pulls
myapp:1.2.0on Wednesday during an autoscaling event.
Now Node A and Node B are running two different versions of the software under the exact same deployment manifest!
2. Supply Chain Attacks & Tag Hijacking
If an attacker compromises a vendor’s registry credentials or typosquats a popular tag, they can overwrite an existing tag (e.g. python:3.11-slim) with a malicious payload. Systems using mutable tags will pull the malicious payload during their next build or pod restart.
3. Broken Caching & Flaky Tests
CI/CD pipelines relying on mutable base image tags may experience non-reproducible test failures when upstream base images undergo silent updates.
How to Work with Image Digests
1. Pulling Images by Digest
You can pass the @sha256:... digest string directly to docker pull or docker run:
docker pull redis@sha256:590c29f656722dca8f176b63f274a1d46b7a329ef312a32c28657bc3b9b47e47
2. Finding an Image Digest
To retrieve the digest of an image from a remote registry without pulling all layers, use docker buildx imagetools or skopeo:
# Using Docker Buildx
docker buildx imagetools inspect nginx:1.25 --format '{{.Manifest.Digest}}'
# Using Skopeo
skopeo inspect docker://docker.io/library/nginx:1.25 | jq -r '.Digest'
To find the digest of a locally pulled image:
docker inspect --format='{{index .RepoDigests 0}}' nginx:1.25
3. Pinning Base Images in Dockerfiles
Always combine human-readable tags with image digests in Dockerfiles for maximum clarity and immutability:
# Good: Human tag for readability + exact SHA-256 digest for immutability
FROM python:3.11-slim@sha256:7f920268809e25b1897d975a59f51ef67e2a9b31d3d63d0c41d1a1b15494f1c9
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "app.py"]
4. Pinning Images in Kubernetes Manifests
apiVersion: apps/v1
kind: Deployment
metadata:
name: payment-service
spec:
replicas: 3
template:
spec:
containers:
- name: payment-api
# Absolute digest pinning guarantees identical execution on all nodes
image: myregistry.com/finance/payment-api@sha256:8a12bc9031ef09a7b...
Automated Digest Maintenance Tools
Manually updating SHA-256 digests in source code can become tedious. Automated dependency bots simplify this process:
- Renovate Bot: Automatically scans Dockerfiles and Kubernetes manifests, detects digest updates for base tags, and opens automated pull requests.
- Kustomize / Helm: Can automatically resolve and pin image digests during deployment manifest generation.
Summary Comparison
| Feature | Mutable Tags (:1.25) | Image Digests (@sha256:...) |
|---|---|---|
| Immutability | No (can be overwritten) | Yes (cryptographically locked) |
| Reproducibility | Variable | 100% Bit-for-bit exact |
| Security Posture | Vulnerable to tag drift | Immune to silent upstream changes |
| Readability | High | Low (long hash string) |
| Recommended Strategy | Combined (:tag@sha256:...) | Combined (:tag@sha256:...) |
Pinning container images by digest ensures your development, staging, and production clusters run identical, untampered code.