You own image naming for an organisation with dozens of services and multiple environments. Design the tagging scheme — which tags exist, which may move, and what deployments actually reference — and justify the tradeoffs.

## The decision the scheme has to make Every image reference in the organisation answers one of three questions, and a good scheme keeps them separate: 1. *Which artifact is this?* — needs an immutable name. 2. *Which version line does it belong to?* — needs a human-meaningful, possibly moving name. 3. *What is running where?* — needs a record, not a tag. Most bad schemes fail by making one tag do all three. `myapp:prod` is the classic: it is simultaneously an identity, a version, and an environment pointer, and because it must move on every release it can be none of them reliably. ## The two tag classes **Immutable tags — one per build.** - `myapp:1.4.2` — the release identity, following semantic versioning so consumers can reason about compatibility. - `myapp:sha-9f3c1ab` — the build identity, tied to the exact commit. Every build gets one, including builds that never become releases. This is what makes "which commit is this container?" answerable without a lookup table. - `myapp:1.5.0-rc.1`, `1.5.0-alpha.4` — pre-releases, still immutable. Enforce immutability at the registry: most registries support a per-repository rule that rejects a push to an existing tag. That converts an accidental repush from a silent artifact swap into a failed pipeline. If the registry cannot enforce it, a CI pre-check (`crane digest` returns non-error → fail) is a workable second best. **Rolling tags — pointers for humans.** - `myapp:1.4` → latest patch on the 1.4 line; `myapp:1` → latest minor on the 1 line; `myapp:latest`, `myapp:stable`. These exist so a developer can `docker run myapp:1.4` without looking anything up, and so dependency bots have something to watch. They are explicitly *forbidden* in Dockerfiles, deployment manifests, and anything a pipeline consumes. ## What deployments reference Digests. CI pushes `1.4.2`, immediately resolves it (`crane digest`), and writes `registry/myapp@sha256:…` into the environment's config repository along with the tag it came from, the commit, and the build URL. Deployment tooling applies that. Two properties follow: - *Every environment's state is a git history.* "What changed in prod between Tuesday and Thursday?" is a diff, with authors and reviews. - *Substitution is impossible.* Nothing between build and run can put different bytes behind the name. Back this with admission policy: reject images referenced by tag, and optionally require a valid signature over the digest. Policy on digests rather than tags is the only enforcement that cannot be defeated by a repush. ## Environment must not be a tag Encoding environments in tags (`:prod`, `:staging`) is attractive because promotion becomes `docker tag`. That is exactly the problem: promotion becomes a *mutation of a shared name*, so at any instant `:prod` means "whatever the last promotion said", nothing has a stable identity, rollback has no target, and two concurrent promotions race. The better model separates *artifact* from *placement*. The artifact is a digest. Placement is a declarative record. If you want environment separation to also carry access-control and retention meaning, promote by **copying the manifest** into a production repository — `crane copy staging/myapp@sha256:… prod/myapp:1.4.2` — asserting the digest is unchanged. Now production has its own credentials, its own retention policy, and possibly its own registry, while the artifact remains provably identical. ## Repository layout One repository per service, namespaced by team or domain: `registry.example.com/payments/ledger-api`. Avoid one repository with tags distinguishing services — it breaks per-service access control, retention, and quota. Keep tags parseable: a fixed, documented grammar makes retention rules ("keep all `sha-*` for 30 days, keep all semver releases for 2 years, keep the last 10 pre-releases") mechanical rather than regex archaeology. ## Retention, and the pin-rot trap Retention interacts with digest pinning: garbage collection removes untagged manifests, and a pinned-but-untagged manifest will eventually disappear. Since every deploy-eligible build keeps a permanent immutable tag, deployed digests stay tagged and therefore retained. Prune aggressively in the `sha-*` space, conservatively in the release space, and keep anything currently referenced by any environment config — which you can compute, because those references are in git. ## Tradeoffs to state out loud - **Discipline cost.** Digest references are unreadable, so tooling must show the tag/commit alongside them everywhere a human looks: dashboards, alerts, deployment records. - **Tag explosion.** A `sha-*` tag per build creates many tags; retention must handle it, and the registry's tag-listing API can get slow with tens of thousands. - **Cross-registry copies cost bandwidth and must carry signatures and attestations**, or production policy checks fail on artifacts that passed in staging. - **Semver requires judgement.** For internal services with a single consumer, `major.minor.patch` is often ceremony; date-based or build-number releases plus commit SHAs can be honest and cheaper. What is not optional is *immutability* — the version grammar is negotiable, the guarantee is not. The defensible summary: immutable tags name artifacts, rolling tags help humans, digests are what run, and environments are declarations in git.