Promotion across environments — same artifact, different environments

Promotion is the practice of moving the same artifact from one environment to the next without rebuilding it. The same digest that passed integration tests is the same digest that gets deployed to staging; the same digest that survived staging is the same digest that gets deployed to production. The bytes never change; only the location changes. Promotion is what makes a CI/CD pipeline a deployment pipeline rather than four independent build pipelines.

Why promotion matters

The production rule of testing is: test what you deploy; deploy what you test. The rule is impossible to honour if the artifact is rebuilt between the test environment and the production environment. The rebuild changes the bytes, the bytes change the digest, and the digest that passed tests is not the digest that runs in production.

flowchart LR
    A["Commit sha"] --> B["Build once"]
    B --> C["Digest sha256:abc"]
    C --> D["Integration tests pass"]
    C --> E["Deploy to staging"]
    C --> F["Deploy to production"]
    E --> G["Smoke tests pass"]
    F --> H["Live traffic"]

The diagram is the promotion model: one build, one digest, many environments. Every environment consumes the same bytes. The tests run against the same bytes the production deployment runs against; the audit trail links production to the commit through the digest.

The pipeline shape for promotion

A promotion pipeline has three stages: build, record, deploy. The build stage produces the artifact at the commit. The record stage resolves the manifest digest and writes it to the deployment manifests. The deploy stage applies the manifests, environment by environment.

docker build --tag app:$COMMIT_SHA .
docker push registry.example.com/app:$COMMIT_SHA
DIGEST=$(crane manifest digest registry.example.com/app:$COMMIT_SHA)
sed -i "s|@sha256:PLACEHOLDER|@sha256:$DIGEST|g" deploy/*.yaml

The sed substitution replaces the placeholder digest in every deployment manifest with the digest the build produced. The same digest appears in dev, staging, and production manifests. The deployment stage applies the manifests to each cluster; the artifact pulled into each cluster is byte-identical.

What goes wrong without promotion

A team that rebuilds per environment typically runs a separate pipeline per environment: dev builds at commit X, staging builds at commit X, production builds at commit X+1 or X-1 depending on the hotfix branch. The artifacts have different digests. The tests run against one set of bytes; production runs a different set.

The cost is not visible at first. The cost is visible the first time a bug appears in production that did not appear in staging: the team has no diagnostic move left, because the artifact in production is not the artifact that was tested, and the differences are not in the source diff but in the build process.

Promotion and runtime configuration

Environment-specific configuration — database URLs, feature flags, secrets, log levels — is not part of the artifact. The artifact is environment-agnostic; the orchestrator (Kubernetes, ECS, Nomad) supplies the configuration at runtime. The difference between a staging deployment and a production deployment is the ConfigMap and the Secret, not the image.

Production discipline

1. Build once at the commit. The pipeline produces a single artifact; every environment consumes the same artifact.
2. Record the digest at build time. The pipeline that pushes by tag also resolves the digest and writes it into every deployment manifest.
3. Inject environment config at runtime. The orchestrator supplies ConfigMap, Secret, and env entries; the artifact does not contain environment-specific values.

Cross-course references

• Git, CI/CD & GitOps — Part XLV-02 (Digests) establishes the digest reference this lesson propagates across environments.
• Terraform for Production Sysadmins — Part XIV (Plan/Apply) applies the same promotion discipline to Terraform plan files.
• Kubernetes for Production Sysadmins — Part V (Workloads) covers the runtime-config injection pattern in detail.

Quiz