3.1.3.3 Image Release Versioning

Image release versioning is the practice of tagging built images with a meaningful, consistent scheme that identifies which version of an application a given image represents, making it possible to track, communicate about, and deploy specific releases deliberately.

Common Versioning Schemes

Many teams adopt semantic versioning for image tags, where the version number communicates the nature of the change relative to the previous release.

docker build -t registry.example.com/myapp:2.3.0 .
docker push registry.example.com/myapp:2.3.0

Others tag images by the commit hash that produced them, which ties every image directly and unambiguously back to the exact source code it was built from.

docker build -t registry.example.com/myapp:$(git rev-parse --short HEAD) .

Multiple Tags for the Same Image

A single built image can carry multiple tags simultaneously — a specific version, and a more general "latest stable" pointer — letting different consumers reference the same content at different levels of specificity.

docker tag myapp:2.3.0 myapp:latest
docker push myapp:2.3.0
docker push myapp:latest

Why Avoiding Ambiguous Tags for Releases Matters

Relying solely on a moving tag like latest for production deployments makes it unclear, after the fact, exactly which version is currently running, since that tag's meaning changes every time a new image is pushed under it.

docker run -d registry.example.com/myapp:2.3.0

Deploying by a specific, stable version tag (or by digest) rather than latest keeps deployment history unambiguous and makes rollback straightforward.

Versioning and Traceability

A consistent versioning scheme, combined with build metadata such as the commit hash, makes it possible to trace any running container back to the exact source code, build configuration, and dependency versions that produced it.

docker inspect myapp:2.3.0 --format '{{index .Config.Labels "git.commit"}}'

Embedding the source commit hash as an image label is a common way to preserve this traceability directly within the image's own metadata.

Why Release Versioning Matters

A clear, consistent versioning scheme is what turns a collection of built images into an understandable release history, supporting confident rollback, clear communication about what is deployed where, and reliable traceability back to source code.