Skip to content
Blog

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.0 on Monday.
  • A hotfix was pushed to myapp:1.2.0 on Tuesday without bumping the version tag.
  • Node B pulls myapp:1.2.0 on 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

FeatureMutable Tags (:1.25)Image Digests (@sha256:...)
ImmutabilityNo (can be overwritten)Yes (cryptographically locked)
ReproducibilityVariable100% Bit-for-bit exact
Security PostureVulnerable to tag driftImmune to silent upstream changes
ReadabilityHighLow (long hash string)
Recommended StrategyCombined (:tag@sha256:...)Combined (:tag@sha256:...)

Pinning container images by digest ensures your development, staging, and production clusters run identical, untampered code.