Immutable artifact promotion means a release candidate is built once, identified by a cryptographic digest, tested as that exact object, and promoted to later environments without recompilation or repackaging. The practice closes a subtle integrity gap. When staging and production each run a separate build, they may use different dependencies, mutable base images, timestamps, compiler behavior, generated assets, or injected values. Passing staging then proves something about the staging artifact, not necessarily the bytes delivered to customers.
Promotion does not require every environment to be identical. It requires a disciplined boundary: executable artifact inside; environment configuration, secrets, routing, scaling, and policy outside. The release record binds a digest to provenance, verification results, and an ordered promotion history. SLSA 1.2 defines provenance as verifiable information about where, when, and how an artifact was produced. Promotion preserves that identity so evidence accumulates around one subject instead of fragmenting across near-equivalent builds.
Define the immutable artifact contract
Choose the promotion unit and make it addressable by digest. It may be an OCI image manifest, package archive, signed binary bundle, mobile application, infrastructure module, or a coordinated release manifest containing several component digests. A human-friendly version can point to the object, but mutable tags such as latest, candidate, and production are references, not identity. The contract should state which files belong to the artifact, how its digest is calculated, where it is stored, which metadata accompanies it, how retention works, and whether the registry prevents overwrite or deletion during the release and rollback period.
| Concern | Artifact | Deployment configuration | Secret system |
|---|---|---|---|
| Application code and static assets | Included and digested | No | No |
| Feature endpoint or environment name | Read through stable interface | Environment-specific value | No |
| Database credential | No | Reference only | Secret value and rotation |
| Replica count and traffic weight | No | Versioned desired state | No |
| Schema migration | Versioned migration code | Execution policy and gate | Migration credential |
| Observability labels | Instrumentation support | Release and environment labels | Exporter credential if needed |
Separate configuration and secrets from the build
Compile-time environment substitution is the most common reason teams rebuild. Replace it with runtime configuration through command arguments, environment variables, mounted files, configuration APIs, or a small boot-time configuration document. Define a typed schema with defaults, allowed ranges, ownership, compatibility, and validation. The application should fail clearly when a required value is absent rather than silently embedding a developer default. Browser applications can fetch a non-secret environment document before initialization; do not treat client-visible configuration as a secret merely because it was once injected during bundling.
Secrets remain references in versioned deployment state and values in a dedicated secret manager. Grant the deployment identity permission to resolve only what its environment needs. Rotation should not alter the artifact digest. When configuration changes behavior materially, version and test that configuration as a release input even though it remains outside the binary. This distinction prevents a false claim that identical bytes guarantee identical behavior; promotion guarantees artifact equivalence, while configuration controls and environment tests establish deployment equivalence.
Build, sign, and record the artifact once
The build job resolves inputs, produces the artifact, uploads it to immutable storage, and captures the registry-reported digest. Generate an SBOM and provenance against that digest, then sign or attest through an identity tied to the controlled builder. GitHub's artifact attestation workflow supports binaries and container images. Keep signing authorization out of untrusted pull-request jobs, minimize build permissions, pin build dependencies, and record the source revision, build definition, builder identity, and resolved dependencies.
Verification is a policy decision, not merely a successful cryptographic operation. Cosign verification checks signatures and can constrain certificate identity and issuer; policy must also verify the expected repository, workflow, builder, source reference, and subject digest. Store the verification result with the release record. A valid signature from an unexpected workflow should fail just as an unsigned image would. Use a documented exception path for emergency or legacy artifacts, with scope, approver, expiry, and compensating review.
Design gates that add evidence to one digest
| Stage | Evidence added | Identity check | Failure action |
|---|---|---|---|
| Build | Tests, SBOM, provenance, vulnerability result | Output digest captured | Reject candidate |
| Integration | Contract and migration rehearsal | Deploy recorded digest | Quarantine candidate |
| Preproduction | Performance, security, operational checks | Compare runtime digest | Stop promotion |
| Production canary | Customer SLIs and guardrails | Canary uses approved digest | Remove traffic or roll back |
| Full production | Deployment status and audit event | All replicas converge on digest | Investigate drift |
Each gate should consume the release record and append evidence without changing the subject. Promote by updating desired state to the approved digest, not by pulling an image and pushing a newly assembled copy. Registry-to-registry transfer is acceptable when it preserves the manifest and content digests; verify both ends. If a tool imports and rewrites metadata, compression, signatures, or a multi-platform index, treat the result as a new artifact requiring a new evidence chain. The simplest model is one trusted registry with repository permissions and environment-specific deployment authorization.
Version deployment desired state
Record environment configuration and the promoted digest in version control or an equivalent immutable change log. The OpenGitOps principles call for declarative desired state that is versioned and immutable, pulled automatically, and continuously reconciled. A promotion request should therefore be a small, reviewable change from digest A to digest B plus compatible configuration. The deployment controller reports actual state, and policy rejects mutable references or unverified subjects. Separate application build permission from production promotion permission so no single compromised job can both create and release arbitrary bytes.
A release manifest is useful for services that move together. It maps component names and platforms to immutable digests, migration versions, configuration schema versions, and evidence locations. Promote the manifest by digest, then resolve its members without mutation. Avoid making the manifest a place to hide environment-specific rebuilds. Its purpose is coordination and traceability: operations can answer exactly which component set ran, which evidence approved it, and which prior manifest restores the previous state.
Rollback by artifact identity
Rollback changes desired state back to a previously verified digest and compatible configuration. Keep artifacts, attestations, SBOMs, migration records, and configuration revisions for the full rollback horizon. Test restoration from the registry rather than assuming a tag remains. Data evolution is the hard boundary: use backward-compatible expand-and-contract migrations, delay destructive changes, and record the last application digest compatible with each schema state. When rollback cannot restore data semantics, define a roll-forward or restore-from-backup decision before deployment.
Continuously compare declared and observed digests. A mutable tag can drift without a deployment event, a node can retain an older image, or a manual hotfix can bypass the controller. Runtime inventory should report the content digest, release manifest, configuration revision, and environment. Alert on unapproved subjects and prevent garbage collection from deleting active or rollback artifacts. Measure promotion lead time, rebuild count after candidate creation, verification failures, drift duration, rollback success, and artifacts lacking complete evidence.
Rehearse promotion as well as rollback. In a non-production account, deny mutable tags, substitute an artifact with a valid signature from the wrong builder, remove an attestation, present incompatible configuration, interrupt registry replication, and attempt a rollback after ordinary cleanup has run. The release controller should reject each unsafe state with a reason an operator can act on. Record time to restore the prior digest and verify its health. These exercises test the whole chain of registry retention, policy, configuration compatibility, deployment reconciliation, and observability instead of proving only that a deployment command accepts a digest.
Immutable promotion key takeaways
- Use a cryptographic digest as release identity; tags and version labels are references.
- Keep environment configuration and secret values outside the artifact while validating their schemas.
- Generate provenance, SBOM, tests, and signatures against the one build output.
- Make every gate append evidence to the same subject rather than producing a replacement.
- Promote through versioned desired state with separate build and deployment authority.
- Retain prior digests and compatible configuration so rollback restores a known identity.
Immutable artifact promotion FAQ
Can an artifact contain an environment name? It can, but then that build is environment-specific and cannot prove build-once equivalence. Prefer a runtime value unless the environment genuinely requires different executable behavior and accepts a separate evidence chain.
Is retagging a container image a rebuild? No, provided the new tag points to the same manifest digest and the registry does not rewrite content. Deploy and verify by digest because tags can move and do not establish identity.
What if production uses a separate registry? Copy by digest, verify destination content and evidence, and record the transfer. If the transfer changes the manifest or creates a new index, treat it as a new subject and regenerate or link appropriate attestations.
Conclusion
Build once and deploy many is an integrity model, not a slogan. It works when one immutable subject carries its provenance and test history forward, while controlled configuration supplies legitimate environmental differences. Digest-pinned desired state, identity-aware verification, separation of authority, runtime drift checks, and rollback retention turn promotion into a traceable release decision instead of another opportunity to change the software.