An image tagging strategy is a systematic approach to naming Docker images in a CI/CD pipeline that ensures traceability, facilitates rollbacks, and enables consistent deployment across environments.
An image tagging strategy defines how you name and version your Docker images as they move through the CI/CD pipeline. It's a critical practice that determines your ability to track which version of code is running in production, quickly roll back to a previous working version, and maintain clear audit trails for compliance. A good tagging strategy balances human readability with uniqueness, ensuring that every build produces a distinct, identifiable artifact.
The simplest and most reliable strategy is using the Git commit hash as the image tag. This creates a direct, immutable link between your code and the built image. You can always trace a running container back to the exact source code that produced it, and you can confidently deploy any historical version by referencing its commit hash. This approach scales well and eliminates ambiguity about what code is running where.
Many teams combine commit hashes with semantic versioning for releases. During development, tags might use branch names and commit SHAs (e.g., feature-login-a47b2c9). When creating an official release, you tag the image with a semantic version like 1.2.3, plus optionally latest to indicate the most recent stable version. This gives you both precise traceability and human-friendly version numbers for communicating releases.
Git Commit SHA:
my-app:a47b2c91– Most traceable, always unique, great for immutable infrastructureSemantic Versioning:
my-app:1.2.3– Human-readable, follows release cycles, good for communicating with usersBranch-based:
my-app:main,my-app:feature-login– Useful for testing feature branches in staging environmentsTimestamp-based:
my-app:20240319-1430– Simple, chronologically sortable, good for automated nightly buildsMulti-tagging: Combining multiple tags on the same image (e.g.,
1.2.3,latest, andmain-a47b2c9) gives both traceability and convenience
The latest tag requires special consideration. While convenient, it's also ambiguous because it changes over time—what was latest yesterday is different from latest today. Many teams restrict latest to only the most recent stable release, or avoid it entirely in production deployments. When you need to roll back, using a commit hash or semantic version is unambiguous, while latest would deploy whatever the newest image happens to be.
Make tags immutable: Never overwrite an existing tag. Each build should produce a new, unique tag to maintain auditability and enable precise rollbacks .
Include build metadata: Embed the build number or timestamp alongside the commit hash to correlate images with CI/CD job runs .
Use multiple tags: Push the same image with several tags—for example, both the commit hash and the branch name—to support different deployment workflows .
Clean up old tags: Implement retention policies in your registry to avoid accumulating millions of outdated images .
Document your strategy: Make sure your team understands how tags are generated and when to use which tags for deployments .