Automating Image Promotion Across Environments
In this lesson, you’ll learn how to implement a promotion workflow that ensures the exact same container binary moves from staging to production without ever triggering a new build.
The Problem with Rebuilding
A common anti-pattern in CI/CD is rebuilding the container image for every environment. If you run docker build for Staging and then again for Production, you introduce non-deterministic variables—such as shifting upstream dependencies, different library versions, or local cache discrepancies. This violates the principle of immutability and creates a scenario where the application you tested in Staging is technically different from the one running in Production.
The Promotion Pattern: Tag and Retag
Instead of rebuilding, you treat your container image as an immutable artifact. Once the image passes its automated security scanning and integration tests in your staging registry, the CI/CD pipeline "promotes" it by applying a new tag or copying the manifest to a production-ready registry namespace.
Consider this logic in your CI/CD pipeline workflow:
# Conceptual promotion step
promote_image:
stage: promote
script:
# Pull the image that passed staging tests
- docker pull registry.internal/app:staging-sha-abc123
# Retag for production release
- docker tag registry.internal/app:staging-sha-abc123 registry.internal/app:prod-v1.2.0
# Push to the production registry namespace
- docker push registry.internal/app:prod-v1.2.0
By using the specific SHA or the tested staging tag as the source, you ensure that the bits inside the container remain identical. The production environment is then updated to point to the new prod-v1.2.0 tag. Because the binary has already been validated, the deployment process effectively becomes a configuration update (using IaC) rather than a software build process. This reduces pipeline execution time and eliminates the risk of "it worked in staging, but not in prod" issues caused by hidden build-time environmental differences.
Key Takeaway: Promotion must be a process of relabeling and moving verified, immutable artifacts rather than re-compiling code, ensuring that the exact binary tested in staging is the only one permitted to execute in production.