Artifact Promotion: Build Once, Deploy Everywhere

WHY IT EXISTS: Teams adopt artifact promotion to solve a painful and common problem: a release passes all tests in staging but fails in production, even when deployed from the same source code commit. This happens because rebuilding the software for each environment can introduce subtle differences—a newer base image, a different dependency version, or a compiler flag change—creating environment drift and making tests unreliable.

THE MENTAL MODEL: Treat your software artifact like a stamped and sealed package. You build the package once, run it through a series of quality checks in one environment, and if it passes, you ship that exact same sealed package to the next environment. You don't go back to the blueprint and build a new one, hoping it's identical. The artifact itself, not the source code commit, is the unit of promotion.

HOW IT WORKS: The process is straightforward. First, a CI job builds the application into an artifact, like a container image. Second, this artifact is identified by an immutable, unique identifier, such as its SHA256 digest. Third, all subsequent pipeline stages (integration testing, staging deployment, security scans) use this exact identifier to pull and test the artifact. Finally, a promotion job deploys the same verified artifact to production. Environment-specific configuration like secrets or database URLs is injected at runtime, not baked into the artifact.

WHEN TO USE IT: Use artifact promotion when release reliability and traceability are critical. It is essential for systems with multiple deployment environments (dev, staging, prod), especially in complex microservice architectures where consistency is paramount. It also simplifies rollbacks, as you are just re-promoting a previously known-good artifact digest instead of performing a risky emergency rebuild.

WHEN NOT TO USE IT: The pattern might be overkill for very simple projects with a single deployment environment or for early-stage prototypes where speed is the only concern and the risk of drift is low. However, adopting the practice early prevents painful migrations later as the system grows. The main trade-off is a slightly more disciplined pipeline setup, which is nearly always a worthwhile investment.

ONE CANONICAL EXAMPLE: A SaaS platform experienced production failures despite successful staging deployments on the same git commit. An investigation found that a production rebuild pulled a newer base container image layer than the one tested in staging. The code was identical, but the artifact was not. They switched to a build-once pipeline that promoted the exact, tested image digest through all environments, eliminating this entire class of errors.