Why tag a container image with the short git commit SHA rather than an incrementing build number?

### What the immutable tag has to buy you Every deploy tag scheme is trying to buy three things: **traceability** (from a running container back to source), **uniqueness** (no two builds ever share a name), and **order** (which of these two is newer). A short commit SHA and an incrementing build number each buy some of that, and the interesting part of this question is which they miss. ### Where the commit SHA wins *Traceability is direct.* `indexer:7e1c94d` is not a lookup key into a build system — it is the commit. During an incident you paste it into `git show` and read the diff. If your build system is down, unavailable to you, or has rotated its history, the tag still means something. A build number is a foreign key into a database you must be able to reach. *It needs no coordination.* The SHA exists the moment the code is checked out. Nothing has to allocate it, so two pipelines, a re-run of an old branch and a developer building locally all produce non-colliding tags with no shared counter. Build numbers are allocated per pipeline definition, so the same integer can be produced by two different pipelines, and moving or re-creating a pipeline often resets the sequence. *It is stable across retries.* Re-running a failed pipeline on the same commit gives you the same tag — usually what you want, since the intent is "produce the image for this commit". ### Where the commit SHA loses *There is no order.* This is the real cost, and it shows up constantly in operations. Given `indexer:7e1c94d` in production and `indexer:a4f0b12` in staging, nothing in those two strings tells you which is ahead. A registry tag listing sorted alphabetically is noise. Answering "is production behind?" requires going back to git, or to a deployment record, every single time. *Re-running is a double-edged sword.* Because a re-run produces the same tag, the second push **re-points that tag to different bytes** if anything outside the commit has changed — a floating base image tag, a package index that moved, a changed build argument. The name is now ambiguous, and it is ambiguous in the worst possible way, because everyone assumes a SHA tag is immutable. Two defences exist: make the pipeline refuse to overwrite an existing build tag (registries can be configured to reject a tag that already exists, though that is a registry-side control), or make the tag unique per run by including the run identifier. *Short SHAs can collide.* A seven-character abbreviation is fine for a small repository and gets less fine as history grows; git itself lengthens abbreviations over time for this reason. It is a small risk, but it is a reason not to shorten aggressively. ### Where the build number wins It sorts. `4183` is obviously later than `4102`. It is also short, easy to say out loud, and maps one-to-one onto a pipeline run with its logs, its test results and its approvals — useful when the question is "where is the evidence for this build" rather than "what source is this". ### Why teams end up combining them The common resolution is not to choose. A tag such as `indexer:1.4.2-4183-7e1c94d` carries a version for humans, a build number that gives order and unique-per-run identity, and a commit SHA that gives traceability. It is long, and nobody types it by hand — but nobody should be typing deploy tags by hand anyway; the pipeline emits it and the deployment record stores it. Whatever the composition, the properties that actually matter are the same: - **Written exactly once.** No later build may ever reuse that string. This is the property the whole rollback story rests on. - **Derivable from the build, not invented at deploy time.** A tag that a human types during a release is a tag that will eventually be typed wrong. - **Reversible to a commit.** You must be able to get from a container back to source without guessing. ### A concrete check A good test of any scheme: page yourself at 03:00 with only the output of `docker ps` on one host. Can you tell, from the image reference alone, which commit it is and whether it is the newest build? A bare SHA tag answers the first and not the second; a bare build number answers the second and not the first. The scheme you pick should answer both without asking you to look anything up first.