Artifact Promotion Across Environments Workflow
Build once and promote the identical artifact through dev, staging, and production gates, where each promotion is a metadata move, not a rebuild.
Objective
Guarantee the artifact tested in staging is byte-identical to the one deployed to production by making promotion a registry operation.
Environment
- An artifact registry with immutable artifacts
- Deployment pipelines per environment referencing registry digests
- Promotion approvals per environment
Steps
1. Build once, attach provenance
Produce a single artifact from a tagged commit, record its digest, build URL, and test results as immutable metadata.
Expected state: The artifact exists in the registry with provenance metadata that cannot be edited afterward.
2. Deploy by digest
Configure every environment pipeline to deploy by registry digest rather than by mutable tag or branch name.
Expected state: Deploy logs show the digest resolved at deploy time, identical across environments.
3. Gate each promotion
Require the environment-specific checks to pass before the digest moves: integration tests for staging entry, sign-offs for production entry.
Expected state: Promotion events appear in an audit log with actor, gate evidence, and timestamp.
4. Promote by moving a pointer
Advance the environment pointer (channel or tag) to the verified digest in the registry; never rebuild or retag over an existing artifact.
Expected state: The registry shows one artifact with multiple environment pointers, not near-duplicate artifacts per environment.
5. Verify production matches staging
After production deploy, compare the deployed digest against the one that passed staging gates and alert on any mismatch.
Expected state: A post-deploy check confirms the production digest equals the staging-approved digest.
Decision points
Rebuild for production with production flags?
- Never rebuild
- Rebuild with env-specific flags
Never rebuild: encode environment differences in configuration injected at deploy time, not into artifact bytes.
Automatic dev-to-staging promotion?
- Auto after green CI
- Manual approval
Auto into staging to keep the pipeline warm; manual approval only for the staging-to-production step.
Expected outcome
A single immutable artifact promoted through gates, with production provably running the bytes that passed staging, and a full audit trail of who promoted what when.
Verification
Registry audit log shows pointer moves with gate evidence; the production deployment manifest references the same digest recorded at staging sign-off.
The artifact that passed testing is the artifact that ships
Rebuilding for each environment reintroduces every nondeterminism the tests just ruled out: dependency drift, different flags, different clocks. Promoting one immutable digest instead makes environment promotion a metadata operation that cannot change behavior.
registry: app@sha256:9f21c4...
build: run #4821 (tag v1.8.0, commit 7ab3e1)
tests: 412/412 green
pointers (promotion = pointer move):
dev -> sha256:9f21c4... (auto after green)
staging -> sha256:9f21c4... (after integration suite)
prod -> sha256:9f21c4... (after sign-offs)
audit: staging->prod by ops@team, gate: release-checklist #88, 14:02ZEnvironment differences live outside the bytes
Every argument for rebuilding (production flags, credentials, endpoints) is an argument for configuration injection at deploy time. Once the artifact is byte-stable, the staging-passed production-deployed guarantee is structural rather than aspirational.
Pointer moves are the audit trail
A promotion recorded as a pointer move with actor and gate evidence answers the supply-chain question permanently: which bytes, who advanced them, on what evidence. Rebuild-based pipelines can only answer approximately, because each environment has different bytes.