Build once, promote many: immutable artifacts

One build, one identity: the digest is the artifact

In the next ten minutes you will understand why two builds of the same commit can produce a crash in production with an empty git diff — and exactly what to pin so it never happens again.

The 12-factor model splits a deploy into three stages: build transforms your code repo into an executable bundle at a specific commit; release combines that exact build with the deploy’s config; run launches a process from a release. The hard rule is directionality — you cannot mutate code at run time and have it flow back into the build. “A release cannot be mutated once it is created.” Each gets a unique ID so you always know precisely what is running.

Build-once-deploy-many is the operational consequence: the build stage runs exactly one time per change, and what it produces is an immutable artifact. For a container, that artifact’s true identity is not its tag — it is its content digest, a sha256 hash of the image manifest. A tag like :latest, :v1.4, or node:22 is a mutable pointer; it can be re-aimed at different content at any moment. A digest is content-addressable: sha256:9b2f… is computed from the bytes, so any change — even one byte — yields a different digest. Pulling by digest guarantees you get the exact image that was built and tested, on every node, in every environment. The digest is the artifact; the tag is just a sticky note on top of it.

Promotion, then, is not a rebuild. It is moving that one digest forward — staging validated sha256:9b2f…, so production runs sha256:9b2f…, the same bytes, unchanged. What does change between environments is config, and that is injected at run time.

Config is per-environment; the bytes are not

If staging and prod run the same artifact, where do the database URL, the API keys, the feature flags live? Not in the image. The 12-factor config factor is blunt: store config in the environment, keep a strict separation between config and code, and the litmus test is that you could open-source the build tomorrow without leaking a single credential. Config is everything that varies between deploys; the artifact is everything that does not.

release = immutable artifact (sha256 digest)  +  per-environment config (injected at runtime)

Concretely, the same digest is launched in each environment with config supplied as environment variables, a mounted ConfigMap, or secrets pulled from a vault — never baked into a layer. Bake DATABASE_URL=staging-db into the image and you have just created a staging-only artifact: you are now forced to rebuild for prod, which reintroduces exactly the drift this principle exists to kill.

Rebuild drift: the empty-diff outage

Here is the failure mode that costs the most incident hours, precisely because there is nothing to look at. When a pipeline rebuilds the artifact separately for each environment, every rebuild re-resolves whatever is floating: a moving base tag, an unpinned transitive dependency, a latest of some build tool, even transient registry state. Common base tags are re-pushed frequently — for OS security patches a tag like node:22 or python:3.12 resolves to a different digest this month than last month while the tag string never changes. So two builds from the same commit, hours apart, can embed different glibc/musl, a different OpenSSL, a different patch of the runtime. The binaries diverge with no source change to explain it. This is “works in staging, breaks in prod” in its purest, most maddening form.

The contrast in pipeline shape:

# BAD — rebuild per environment, deploy a mutable tag
# staging job
docker build -t myapp:latest .          # resolves node:22 -> digest A
docker push myapp:latest
kubectl set image deploy/app app=myapp:latest   # staging pulls A
# production job, hours later
docker build -t myapp:latest .          # resolves node:22 -> digest B (base re-pushed!)
docker push myapp:latest                # :latest now points at B
kubectl set image deploy/app app=myapp:latest   # prod pulls B — different bytes, empty git diff

# GOOD — build once, capture the digest, promote it, config at runtime
docker buildx build --push -t registry/myapp:1.4.0 --metadata-file out.json .
DIGEST=$(jq -r '."containerimage.digest"' out.json)
# DIGEST = sha256:9b2f...  — the immutable identity, captured ONCE
kubectl set image deploy/app app=registry/myapp@$DIGEST -n staging   # staging runs the digest
# ...staging passes its gates...
kubectl set image deploy/app app=registry/myapp@$DIGEST -n prod      # prod runs the SAME digest
# config differs per env via env vars / ConfigMap / secrets — never rebaked into the image