Skip to content
Tutorials Center
My learning

Topics

Lesson 77 of 111 ยท Registries and CI/CD

Tagging and Versioning Strategies

Choose a Docker tag strategy that makes rollbacks safe: semantic versions, rolling tags, git SHA tags, immutable tags, promotion between registries and why latest hurts.

A tag is a movable label. That single fact explains most Docker deployment accidents: someone pushed a new image to a tag that production already uses, a server restarted and pulled it, and nobody can say which code is running. A good tagging strategy answers three questions at any moment. Which exact build is this? What is the newest release of this line? How do I go back?

This lesson builds a complete strategy from small pieces: full semantic versions, rolling tags, git SHA tags, and digests, then shows how to promote an image from one repository to another without rebuilding it. Every command was run against a local registry:2 (Running a Private Registry) with Docker 29. The registry address 127.0.0.1:18152 appears in the output; in your own setup it is registry.example.com or similar. Read Tags and Registries first if you are unsure what a tag or digest is.

The problem with one tag

Imagine you deploy shop/web:latest. Monday it is version 1.4.2. On Tuesday CI pushes 1.4.3 to latest. Wednesday a server restarts and pulls latest; it now runs 1.4.3, while the other two servers still run 1.4.2 because they have not restarted. If 1.4.3 has a bug, you cannot roll back: the label that said 1.4.2 is gone. You do not even know which of your servers runs what.

The root cause is that tags are mutable pointers. A tag names a digest, and a push can change which digest it names. A digest, in contrast, is the SHA-256 of the manifest and never changes. A good strategy gives every build a name that never moves, and layers friendlier moving names on top.

Tag kinds

There are two groups, and a healthy repository uses both:

Kind Example Moves? Use it for
Immutable build tag 1.4.3, sha-51d0e77 Never Deployments, rollbacks, audits
Rolling tag 1.4, 1, latest, stable, staging Yes Convenience for humans and for consumers who want "newest of this line"

Semantic versions

For software that has releases, tag with the full semantic version: MAJOR.MINOR.PATCH. Consumers then pick how much movement they accept: 1.4.3 (exact), 1.4 (latest patch, bug fixes only), 1 (latest minor, new features, same major), or latest. That is why official images publish several tags for one build.

Build once, and apply all the names to the same image:

Terminal
docker build -t shop/web:1.4.2 \
  --build-arg VERSION=1.4.2 --build-arg GIT_SHA=9f3c2ab .

The Dockerfile used here records the version and commit in standard OCI labels, so you can read them back later from any copy of the image:

DOCKERFILE
FROM alpine:3
ARG VERSION=dev
ARG GIT_SHA=unknown
LABEL org.opencontainers.image.version=$VERSION \
      org.opencontainers.image.revision=$GIT_SHA
RUN echo "$VERSION" > /version
CMD ["cat", "/version"]

Now add the other names. docker tag copies nothing; it creates another pointer to the same image. All five names share one image ID:

CONSOLE
$ docker tag 127.0.0.1:18152/shop/web:1.4.2 127.0.0.1:18152/shop/web:1.4
$ docker tag 127.0.0.1:18152/shop/web:1.4.2 127.0.0.1:18152/shop/web:1
$ docker tag 127.0.0.1:18152/shop/web:1.4.2 127.0.0.1:18152/shop/web:latest
$ docker tag 127.0.0.1:18152/shop/web:1.4.2 127.0.0.1:18152/shop/web:sha-9f3c2ab
$ docker image ls 127.0.0.1:18152/shop/web --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}'
REPOSITORY                 TAG           IMAGE ID
127.0.0.1:18152/shop/web   1             c503c84d163f
127.0.0.1:18152/shop/web   1.4           c503c84d163f
127.0.0.1:18152/shop/web   1.4.2         c503c84d163f
127.0.0.1:18152/shop/web   latest        c503c84d163f
127.0.0.1:18152/shop/web   sha-9f3c2ab   c503c84d163f

Push every name. After the push, the registry lists them all:

CONSOLE
$ curl -s http://127.0.0.1:18152/v2/shop/web/tags/list
{"name":"shop/web","tags":["1.4","1.4.2","latest","1","sha-9f3c2ab"]}

(The registry returns tags in its own order, not sorted.) Next week you ship version 1.4.3. Build it, give it its own immutable names, and move the rolling ones:

CONSOLE
$ docker build -q -t 127.0.0.1:18152/shop/web:1.4.3 --build-arg VERSION=1.4.3 --build-arg GIT_SHA=51d0e77 .
$ docker tag 127.0.0.1:18152/shop/web:1.4.3 127.0.0.1:18152/shop/web:1.4
$ docker tag 127.0.0.1:18152/shop/web:1.4.3 127.0.0.1:18152/shop/web:1
$ docker tag 127.0.0.1:18152/shop/web:1.4.3 127.0.0.1:18152/shop/web:latest
$ docker tag 127.0.0.1:18152/shop/web:1.4.3 127.0.0.1:18152/shop/web:sha-51d0e77

After pushing, compare what each tag points to. This digest column comes straight from the registry's API (shortened to 12 hex characters; yours will differ):

TEXT
tag           digest
1.4.2         sha256:c503c84d163f      <- unchanged, still the old release
sha-9f3c2ab   sha256:c503c84d163f      <- same build as 1.4.2
1.4.3         sha256:d6611444934e
1.4           sha256:d6611444934e      <- moved
1             sha256:d6611444934e      <- moved
latest        sha256:d6611444934e      <- moved
sha-51d0e77   sha256:d6611444934e

Rolling tags moved to the new digest, and the immutable ones stayed. Anyone who asks for 1 gets the new release; anyone who needs to roll back still has 1.4.2. Running by tag shows the difference immediately:

CONSOLE
$ docker run --rm 127.0.0.1:18152/shop/web:1
1.4.3
$ docker run --rm 127.0.0.1:18152/shop/web:1.4.2
1.4.2

Git SHA tags

A semantic version is a human decision; a commit SHA is a fact. Tagging each image with the short commit hash (sha-51d0e77) gives you a name you can compute in CI without anyone deciding anything, and it points straight to the source: git show 51d0e77. SHA tags are ideal for every branch build and for test environments, because every commit gets its own image and nothing collides. Many teams use only SHA tags for development and add a semver tag when a release is cut.

Combine them. Production deploys the semver tag (or digest); the SHA tag exists so anyone can go from "the thing running in production" to "the exact commit". The OCI labels do the same job from inside the image:

CONSOLE
$ docker image inspect 127.0.0.1:18152/shop/web:1.4.3 --format '{{json .Config.Labels}}'
{"org.opencontainers.image.revision":"51d0e77","org.opencontainers.image.version":"1.4.3"}

Branch and environment tags

Sometimes a tag is meant to move. main (the latest build of the main branch), staging and production are pointers to a state, not to a version. They are fine for humans and for deploy tooling, provided you also record the immutable name behind them, ideally in a deployment log or in the manifest of your orchestrator.

Do not use rolling tags as the only record of what runs. If a deployment file says image: shop/web:production you cannot answer "what version is this?" or reproduce last week's deployment.

Digests: the tag that cannot move

When you pull, the registry returns the image's digest, and Docker remembers it:

CONSOLE
$ docker image inspect 127.0.0.1:18152/shop/web:1.4.3 --format '{{range .RepoDigests}}{{println .}}{{end}}'
127.0.0.1:18152/shop/web@sha256:d6611444934e59a3cc82c997a80caa2a752b9bbec00a272827a9227d72857304

Using that form in a Compose file or a Kubernetes manifest pins the deployment to one exact set of bytes, whatever anyone does to the tags afterwards:

YAML
services:
  web:
    # 1.4.3 (commit 51d0e77) - keep the readable tag as a comment
    image: registry.example.com/shop/web@sha256:d6611444934e59a3cc82c997a80caa2a752b9bbec00a272827a9227d72857304

You can write both, image: name:1.4.3@sha256:...: Docker then uses the digest and ignores the tag, but humans (and update tools such as Renovate) still see the version. Digest pinning is the strongest guarantee and a good default for production. The cost is that you must update the digest on every release, so automate it.

Immutable tags

Everything above works only if nobody overwrites 1.4.3. Registries differ in how they help:

  • Amazon ECR has a per-repository tag immutability setting; a push to an existing tag is rejected.
  • Harbor and GitLab offer immutability or tag-protection rules that match patterns, such as v*.
  • Plain registry:2 does not enforce it, and not every hosted registry offers it; check yours, and otherwise rely on a CI rule and discipline.

A simple CI guard is to check before pushing. This is a read-only example of the idea:

Terminal
if docker manifest inspect registry.example.com/shop/web:1.4.3 >/dev/null 2>&1; then
  echo "1.4.3 already exists - refusing to overwrite" >&2
  exit 1
fi

Promote, do not rebuild

A typical flow has more than one repository or registry: builds land in a dev area, pass tests, move to staging, and finally to prod. The rule that makes this safe is: build once, promote the same image. If you rebuild for production, you ship something that was never tested, even if the source is identical (a base image or a package index may have changed in between).

Promotion is just copying the manifest to another name. docker buildx imagetools create does it directly between repositories, without pulling the layers to your machine, and keeps the same digest:

CONSOLE
$ docker buildx imagetools create --tag 127.0.0.1:18152/prod/web:1.4.3 127.0.0.1:18152/shop/web:1.4.3
#1 0.003 copying sha256:4b0913e0827e... from 127.0.0.1:18152/shop/web:1.4.3 to 127.0.0.1:18152/prod/web
#1 0.733 pushing sha256:d6611444934e... to 127.0.0.1:18152/prod/web:1.4.3
#1 DONE 0.8s
$ curl -s http://127.0.0.1:18152/v2/_catalog
{"repositories":["prod/web","shop/web"]}
$ docker buildx imagetools inspect 127.0.0.1:18152/prod/web:1.4.3 | head -4
Name:      127.0.0.1:18152/prod/web:1.4.3
MediaType: application/vnd.oci.image.index.v1+json
Digest:    sha256:d6611444934e59a3cc82c997a80caa2a752b9bbec00a272827a9227d72857304

The prod/web:1.4.3 digest is identical to the one in shop/web, so you can prove that production runs what the tests ran. Between registries, docker pull, docker tag, docker push achieves the same; tools such as crane copy and skopeo copy copy without a daemon.

What latest does and does not mean

latest is not special to the registry. It is the tag Docker uses when you do not name one. It does not mean "newest": it means "whatever the last person who pushed latest decided". An image might have 1.5.0 pushed after latest was last moved, or a hotfix branch might have overwritten it. Use it for humans trying things out (docker run alpine), and publish it as a courtesy for your consumers, but never deploy it and never use it as the base of your own Dockerfile in production (FROM node:latest breaks the day a new major version is out).

Choosing a strategy

You are... Tag with
A library or tool published for others Full semver plus rolling MAJOR.MINOR, MAJOR, latest
An internal service, continuous delivery sha-<commit> for every build; a semver or date tag for releases
A team with several environments Immutable build tag, promoted unchanged; rolling staging/production as pointers only
A regulated environment Digest pinning, immutable tags, signatures (Image Security and Scanning)

A few more conventions are worth adopting:

  • Prefix SHA tags (sha-51d0e77) so they cannot be mistaken for versions, and so registries that sort numerically do not confuse them.
  • Use dates carefully. 2026-10-23 works for scheduled rebuilds of the same code (security refreshes) but says nothing about content; combine it with a version (1.4.3-20261023).
  • Include the variant when you publish several: 1.4.3-alpine, 1.4.3-slim. Keep it a suffix so version sorting still works.
  • Tag all platforms together. A multi-platform tag points at an index that holds one image per architecture (Multi-Platform Images). Never publish 1.4.3-arm64 as the only tag of a build unless you want to.
  • Clean up. Delete old SHA tags after a retention period, with a lifecycle rule in the registry, or you will pay to store thousands of dead images.

In CI you rarely type tags by hand. Actions such as docker/metadata-action generate the whole set from a Git tag or branch; a read-only example of the result for a release v1.4.3 of commit 51d0e77:

TEXT
registry.example.com/shop/web:1.4.3
registry.example.com/shop/web:1.4
registry.example.com/shop/web:1
registry.example.com/shop/web:sha-51d0e77
registry.example.com/shop/web:latest

The pipeline lesson (Docker in CI) shows how to wire this up.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why is deploying shop/web:latest risky?

    A tag is mutable. Whoever pushed last decides what latest means, so identical deployments can run different code and the previous version has no stable name.
  2. 2. You release 1.4.3. Which tags should move to the new image and which should stay?

    Rolling tags (1.4, 1, latest) follow the newest release in their line. The immutable 1.4.2 must stay on its original image so you can roll back to it.
  3. 3. What is the benefit of promoting an image with docker buildx imagetools create instead of rebuilding it for production?

    Copying the manifest preserves the digest. A rebuild could pick up a different base image or package versions, even from the same source.
  4. 4. What does a reference like image: shop/web@sha256:d661... in a Compose file guarantee?

    A digest identifies one manifest forever. It says nothing about newness or safety, only about identity.
  5. 5. Why add a sha-<commit> tag next to the semver tag?

    A commit SHA is generated automatically and traceable with git. It identifies every build, including ones that are never released.

Summary

  • Tags are mutable pointers to digests. Use immutable tags (1.4.3, sha-51d0e77) for deployments and rolling tags (1.4, 1, latest, staging) only for convenience.
  • On each release, add the full version and a SHA tag, and move the rolling tags; old immutable tags stay for rollbacks.
  • Record version and commit in OCI labels (org.opencontainers.image.version, .revision) so any copy of the image can tell you where it came from.
  • Pin production to a digest (name@sha256:...) when you need an absolute guarantee, and automate updating it.
  • Build once and promote the same image between repositories with docker buildx imagetools create, crane copy or skopeo copy.
  • Turn on immutability in your registry where it exists (ECR, Harbor) or enforce it in CI; never deploy or build from latest.

Next: Docker in CI