Artefact Promotion

An artefact is built once, from a specific commit, and the same bytes progress through every environment. What changes between environments is configuration supplied at deployment, not the artefact.

The alternative — rebuilding per environment — means the thing running in production was never tested, only something built from the same source at a different time with a possibly different dependency resolution, toolchain version or build environment.

Why the distinction matters more than it appears

Builds are not deterministic unless deliberately made so. Unpinned dependencies resolve differently, toolchains update, base images move, and non-deterministic ordering produces different output. A rebuild is a new artefact with a plausible claim to equivalence and no proof.

That claim is exactly what fails at the worst moment: production behaves differently from staging and nobody can explain it, because the difference is in an artefact nobody compared.

Implementation patterns

• Immutable, content-addressed artefacts, so identity is provable rather than asserted. Pin to digests, not to mutable tags — tags pointing at changing content are the source of "it worked yesterday".
• Configuration injected at deployment, never baked in. An artefact carrying environment-specific configuration cannot be promoted.
• Provenance attached — commit, builder, dependency set, pipeline run — so the artefact's origin is verifiable at every stage.
• Promotion recorded as an event, so the path from build to production is auditable.
• Verification at consumption, refusing artefacts whose attestation does not match policy.
• Retention tiered: recent builds hot, releases retained long, intermediates expired automatically.

Industry example

Platforms distributing large artefacts to many consumers combine promotion with a further requirement: the artefact must transfer efficiently. Chunk-level transfer so updating one file does not re-download a multi-gigabyte repository, resumable downloads, and integrity verification are where most of the perceived quality lives, and none of it is possible without stable content-addressed identity.

The inventory property is the one most used in practice. When a dependency vulnerability is announced, "which releases contain this version" must take minutes rather than days — and that query is only answerable if each artefact's dependency set was recorded at build time and the artefact identity is stable.

Failure scenarios

• Rebuilding between environments, so production runs something never tested.
• Mutable tags, where the artefact behind a name changes without notice.
• Configuration baked into the artefact, which forces a rebuild per environment and defeats promotion.
• A registry as a single point of failure — if artefacts cannot be pulled, nothing deploys or scales, including the recovery from the incident that made you want to deploy.
• No inventory, so vulnerability response begins with an investigation.

Trade-offs

Promotion requires configuration to be fully externalised, which is more work up front and occasionally awkward — some frameworks assume build-time configuration. It also requires artefact storage and retention management, since artefacts accumulate.

Against that, it removes an entire class of "works in staging" incident and is a prerequisite for any meaningful provenance claim. For anything beyond a single environment, it is close to non-negotiable.

Interview question

"Your change works in staging and fails in production, with the same commit deployed to both. Give me three explanations, and tell me which one your build process makes impossible."