How to build an environment promotion pipeline

What and why

Rebuilding an app for each environment risks shipping something different to production than you tested. Promotion fixes this: build one immutable artifact, then move that exact artifact through dev, staging, and production. This tutorial sets up a build-once, promote-many pipeline.

Prerequisites

• A pipeline that produces a deployable artifact (a container image here).
• Multiple deploy targets, one per environment.
• Ability to configure protected environments in CI.

Steps

1. Build the artifact once

Build on merge to the main branch and produce a single image. Never rebuild downstream; that would break the guarantee that what you tested is what you ship.

2. Publish with an immutable identifier

Push the image and reference it by digest, not a moving tag:

ghcr.io/acme/web@sha256:abc123...

The digest pins the exact bytes, so every environment runs identical code.

3. Deploy to dev automatically

  deploy-dev:
    environment: dev
    steps:
      - run: ./deploy.sh dev ghcr.io/acme/web@${{ needs.build.outputs.digest }}

Dev deploys with no gate for fast feedback.

4. Promote to staging

Reuse the same digest in a staging job that runs after dev succeeds. No build step appears here, only a deploy.

5. Gate production with approval

  deploy-prod:
    needs: deploy-staging
    environment: production
    steps:
      - run: ./deploy.sh prod ghcr.io/acme/web@${{ needs.build.outputs.digest }}

Configure the production environment to require a reviewer. The job pauses until someone approves.

Verification

Confirm the digest deployed to production matches the one built on merge. The production job should wait for approval and only then run. Each environment's running version should trace back to the same build.

Next Steps

Add automated smoke tests as a gate between stages. Record deployment metadata for auditing. Support rollback by redeploying a previous digest.