13.2.1 Image Promotion Flow

Image promotion flow moves a single, already-built container image through successive environments — development, staging, production — by re-tagging and redeploying that exact same image, rather than rebuilding it separately for each environment, ensuring what's eventually deployed to production is precisely what was already validated earlier in the flow.

Why Promoting the Same Image, Rather Than Rebuilding, Matters

Rebuilding an image separately for each environment risks subtle differences between those builds — a different dependency resolution, a different base image patch version — undermining the assurance that what's tested in staging is truly the same as what reaches production.

docker build -t myapp:${{ github.sha }} .
docker push registry.example.com/myapp:${{ github.sha }}

This single image, built once, is what subsequently gets promoted through each environment, rather than triggering a fresh, potentially divergent build at each stage.

The Basic Promotion Sequence

Each environment's deployment pulls and runs this same, already-built image, simply applying an additional tag to mark its current promotion stage.

docker pull registry.example.com/myapp:${{ github.sha }}
docker tag registry.example.com/myapp:${{ github.sha }} registry.example.com/myapp:staging
docker push registry.example.com/myapp:staging

docker tag registry.example.com/myapp:${{ github.sha }} registry.example.com/myapp:production
docker push registry.example.com/myapp:production

Gating Each Promotion Step on Successful Validation

Promotion to the next environment should only happen after the current environment's validation (automated tests, manual approval) has actually succeeded.

promote-to-production:
  needs: validate-staging
  environment: production

Why Image Promotion Flow Matters

Promoting one validated, immutable image through successive environments, rather than rebuilding separately at each stage, provides a much stronger guarantee that what reaches production is exactly what was already tested and approved earlier in the process.