In a build-once pipeline, promoting a release from staging to production never changes the artifact's bytes. What does promotion actually change, and what must the production deployment reference for that promotion to mean anything?

## Promotion is a change of reference Once a pipeline builds once, "promote to production" cannot mean anything about the artifact — it already exists and is immutable. What changes is a **record**: some system now says *this specific artifact is what production runs*. Every real promotion mechanism is a variation on writing that record: - a version or identity written into a deployment definition that the environment reads; - a release or deployment record inside the delivery system, carrying which artifact, which environment, when, and on whose authority; - a **channel or view** — a named stream such as *stable* — that consumers resolve, with promotion adding the artifact to it; - **metadata attached to the artifact** — a label recording that it passed the staging soak — which downstream steps require before deploying. In a pull-based delivery model the record is the committed desired state that the cluster-side agent reconciles; the same principle applies, only the writer and reader differ. ## Why the reference must be immutable The common shortcut is a moving tag: production deploys `myapp:prod`, and promotion repoints that tag at the newly approved build. It looks elegant and it fails in specific ways. **Split-brain versions.** Nothing resolves the label once, globally. An instance started before the move runs the old build; one started after — an autoscaling event, a node replacement, a crashed process restarting — pulls the new one. You now have two versions serving under one name, with no deployment event to explain it. **Unanswerable provenance.** "What is production running?" resolves to "whatever `prod` points at right now", which is not a historical record. Ten minutes after an incident you cannot reconstruct what was live during it. **Ambiguous rollback.** Rolling back means repointing the label at the previous build — which requires knowing what it was, and requires that artifact still to exist and still to be reachable under some identity. **A weaker control surface.** Anyone able to write that label can change what production runs, without going through the promotion path at all. The fix is to make the deployed reference **content-addressed or otherwise non-reassignable**: production runs `myapp@sha256:...`, or a version string that is never republished. Human-friendly channels remain useful for humans — resolve them once, at promotion time, and record the immutable identity they resolved to. ## What a good promotion record contains At minimum: the artifact's immutable identity; the source commit it was built from; the target environment; the timestamp; and the authority for the decision (which automated gate passed, which person approved). That record is what turns "deployed" into "deployed on purpose" and what makes an audit trail possible after the fact. It is also the input to sensible retention — a store can only protect what a record says was deployed. ## Two anti-patterns dressed up as promotion **Promotion that triggers a build.** A "promote to production" button that re-runs the pipeline against the release branch is not promotion; it produces a new artifact and discards everything pre-production testing established. The tell is that promotion takes as long as a build. **Promotion that produces a variant.** Rebuilding "the same" artifact with production configuration compiled in has the same defect, plus the illusion of continuity because the version number was preserved. ## Making the record authoritative A promotion record only matters if the deploy path cannot be bypassed. That means the production deploy resolves its artifact from the record rather than from a parameter someone types, and the deployment reports back the identity it actually ran so drift between "declared" and "running" is visible. Whether an additional check refuses artifacts lacking a promotion record is an enforcement decision layered on top — but the foundation is the same in every case: one immutable identity, recorded, referenced, and reported. ## The payoff With immutable references and promotion records, three previously fuzzy questions get exact answers: what is running (the identity in the current record), what was running at 03:14 last Tuesday (the record active then), and how do we go back (redeploy the previous record's identity — no build, no ambiguity, seconds rather than minutes).