Why does a CI job push one container image under both a git-SHA tag and a `stable` tag?

### Two jobs, two tags A container image reference like `registry.internal:5000/indexer:7e1c94d` is a name a registry resolves to a manifest. Names are cheap: the same image can carry as many of them as you like, in the same repository, and pushing a second name for an image already in the repository transfers almost nothing because the blobs are already there. That cheapness is what makes the two-tag convention work. A release pipeline is being asked for two different things at once, and they are in direct conflict: 1. **"Run exactly the build we tested."** This needs a name that will mean the same thing forever. If the name can be re-pointed, then "deploy `indexer:stable`" is not an instruction, it is a bet on what somebody else has done since. 2. **"Run whatever is current."** A developer pulling the service to run it locally, a smoke-test job, a `FROM` line in a downstream image — these want the newest good build without being told its identifier every time. That needs a name that *does* move. One tag cannot satisfy both. So the pipeline pushes two. ### What the build tag looks like The immutable tag is derived from something the build already knows and never reuses: the commit that was built (`7e1c94d`), the pipeline's build number (`4183`), a release version, or a combination such as `1.4.2-4183-7e1c94d`. The rule that matters is not which of those you pick — it is that **the pipeline writes that tag once and no later build ever writes it again**. It is the name you put in a deployment, quote in an incident channel, and roll back to. ### What the alias looks like `stable`, `prod`, `edge`, `nightly`, `main` — the exact word is convention. What defines an alias is that it is re-pointed on purpose. Mechanically that is two commands after the build has been pushed: ``` docker tag registry.internal:5000/indexer:7e1c94d registry.internal:5000/indexer:stable docker push registry.internal:5000/indexer:stable ``` Locally, `docker image ls` now shows two rows with the *same* IMAGE ID — `docker tag` did not copy anything, it added a name. In the registry, the second push finds every layer already present ("Layer already exists") and writes only the manifest under the new tag. The previous build that used to be behind `stable` has not been deleted or damaged; it simply is not called `stable` any more. It is still reachable by its own build tag — which is exactly why that build tag has to exist. ### The failure this convention prevents The interesting question is what happens when a team pushes only the alias. Every release overwrites the meaning of the one name that exists. There is then no way to say "run the build from before lunch", because that build has no name at all. Rolling back becomes rebuilding from an older commit and hoping the result is equivalent — a different base image, a moved dependency or a changed build argument means it may not be. Worse, a rollback done by re-pointing the alias backwards is invisible: nothing in the registry records that the name used to mean something else. With both tags present, a rollback is boring: redeploy `indexer:7e1c94d`, which is a name nobody has permission to move, and adjust the alias afterwards if you keep one. ### What each side of the pair is *not* The build tag is not a version. It usually is not ordered — you cannot look at two commit-SHA tags and say which is newer — and it does not tell anybody whether a build is fit for production. That is what the alias, or a separate promotion step, is for. The alias is not an audit trail. It has no history: it is one pointer, and looking at it today tells you nothing about what it pointed at last Tuesday. If knowing that matters — and during an incident it usually does — the record has to live somewhere that keeps history, such as the deployment log that says which immutable tag was rolled out and when. ### The habit to take away Build once, push the immutable tag first, then move any aliases as a separate, deliberate step. Deploy and roll back by the immutable tag. Treat every mutable name as a signpost for humans, never as the thing a production system is pointed at.