Build Once, Promote the Same Bytes

The anti-pattern is comfortable and common: each environment's pipeline checks out the release tag and builds. It feels equivalent — same source, same Dockerfile — and it is not, because a build reads more than your source. It resolves a base image tag that moved. It resolves dependency version ranges that published a patch this morning. It runs on a runner with a different toolchain version, a different locale, a different set of cached layers. Three builds from one commit can produce three different sets of bytes, and only one of them was tested.

The failure that follows is memorable precisely because it looks impossible. Staging is green. The production build runs forty minutes later, pulls a base image whose :3.19 tag now points at a new patch release with a changed TLS default, and the service cannot reach an internal endpoint. Nothing in the commit history explains it, because nothing in the commit history changed.

Build once. Produce one artifact, identify it by the content digest rather than by a tag, and promote *that identifier* through environments. The pipeline stops being "build and deploy, three times" and becomes "build once, then three deployments of the same digest".

A tag is a mutable pointer. v1.4 today and v1.4 tomorrow can reference different content, whether through a re-push after a "tiny fix", a mirror that resolved differently, or a compromised registry account. A digest is the SHA-256 of the image manifest: it either matches or it does not, and it cannot be repointed.

So the deployment manifest should reference the digest. Tags remain useful as human-readable labels and as the thing a person types, but the resolution from tag to digest happens once, at promotion time, and the digest is what is recorded and deployed. This is also what makes signing meaningful — a signature is over a digest, so verifying at deploy time proves the bytes are the ones your build produced.

Two operational consequences fall out. Rollback becomes trivially safe: the previous digest is still in the registry, still signed, still exactly what ran successfully yesterday. And the registry becomes a system of record — "what is running in production?" has an answer that is a hash, and that hash traces to a build, a commit and a reviewer.

If one artifact runs in three environments, then everything that differs between environments must come from outside it: endpoints, credentials, feature-flag defaults, log level, replica bounds. This is a constraint that pays for itself — it forces the configuration boundary to be explicit rather than baked in, which is the same argument Configuration Belongs Outside the Image makes from the image side.

The awkward case is anything resolved at build time. A frontend bundle with an API URL compiled in, a binary with an embedded environment name, a config file copied in during the build — each one forces a rebuild per environment and reintroduces the problem. The fixes are mundane: serve configuration at runtime, read it from the environment, or fetch it at startup from a configuration service.

The promotion record itself is worth keeping. Which digest is in which environment, who approved each promotion, when. During an incident the first question is "what changed?", and a promotion log answers it in one line instead of a git archaeology session.