Image Promotion

What Is Image Promotion?

Image promotion is the practice of moving a single built artifact through environments — development, staging, production — by reference rather than rebuilding it at each stage. The build happens once, and every later environment points at the same content. Promotion changes where an image is trusted, not what it contains, and that distinction is the whole point.

The alternative is to rebuild per environment: a staging build, then a production build from the same source. Those two builds are not the same artifact. Base layers move, mirrors resolve differently, timestamps change, and the thing that passed testing is not the thing that ships.

Promotion is therefore a statement about identity. The digest that cleared the scan in staging is the digest admitted to production, and every gate in between records that same identifier. Anything that changes the identifier starts the sequence again.

How Image Promotion Works

Promotion is a sequence of checks run against one immutable reference.

• The artifact is built once. A single pipeline run produces the image and its digest, and no later stage rebuilds it.
• Each stage is a gate. Scanning, policy evaluation, and signature and provenance verification run against that digest before it advances.
• The copy preserves content. Moving between registries copies the manifest and layers, so the digest survives unchanged.
• The reference travels with it. Deployment manifests name the digest, so what admission sees matches what the gate approved.

A digest is a content address. Under the OCI image specification an image is referenced either by a mutable tag or by an immutable digest, the sha256 of its manifest. Copying cannot change that value; rebuilding almost always does.

Admission closes the chain. A Kubernetes admission controller that rejects any image without a verified signature and an approved digest turns the record into an enforced rule.

What Promotion Guarantees, and What It Does Not

Promotion buys a single subject for every claim. One SBOM, one provenance attestation, one set of scan results and one signature all describe the same bytes, so evidence gathered early stays valid later.

It does not make the artifact safe. A digest that passed four gates is the same image it was at the first, including any flaw nobody had found yet.

The limits are worth stating plainly:

• Findings age. A scan is a judgement at one moment, so a long-lived artifact needs rescanning rather than re-approval.
• Configuration is separate. Environment differences move into config and secrets, which the practice does not cover.
• Tags can betray it. Advancing by tag reintroduces the problem the practice exists to solve.
• Registry separation is not isolation. A production registry limits who may push, but does not verify what arrived.

Advancing by tag is the common failure: a gate approves app:1.4.2, someone pushes a new build to that name, and production pulls content no gate saw.

How to Promote Images Safely in Production Environments

The practice is only as strong as the identifier it moves and the gates that identifier passes.

• Build once per release and treat the resulting digest as the artifact's identity from that point on.
• Copy between registries with a tool that preserves the manifest, and verify the digest on the far side.
• Keep staging and production registries separate, with push rights to production held by the promotion process alone.
• Re-verify signature, provenance and policy at each boundary instead of trusting the previous stage's recorded result.
• Pin deployment manifests to digests and enforce it with an admission policy, so an unapproved image cannot be scheduled.

How Hardened Container Images Fit a Promotion Flow

Promotion carries evidence from stage to stage, so the evidence has to exist at the first stage. A base image that arrives without attestations gives every gate less to check.

Echo's images are built using controlled build infrastructure at SLSA L3, signed and attested, and delivered with SBOM, provenance and VEX (echo.ai/product) — material each gate can verify rather than infer.

That does not replace your own gates. The digest you advance is still yours to verify at every boundary, and a supplier's attestation is evidence, not an exemption.

FAQs

Why not rebuild for each environment?

Because two builds from the same source are rarely the same artifact. Base layers move, mirrors resolve differently and build timestamps change, so the digest differs. If the digest differs, the testing, scanning and approval performed on the first build describe something other than what reaches production. Build once and the evidence keeps its subject.

What should a gate check before an image advances?

At minimum: a current vulnerability scan against the digest, signature verification against a trusted key, provenance naming the expected builder and source, and policy evaluation covering configuration such as non-root execution. Each check should run at the boundary rather than being inherited from the previous stage's record. Inherited approvals are the weakest link.

Can an image be advanced by tag instead of digest?

It can, and the guarantee disappears. A tag is a mutable pointer, so a name approved in staging may point at different content by the time production pulls it. Registry tag immutability removes the overwrite, but a digest is the stronger reference because it is derived from the content itself.

How do environment differences work if the image never changes?

They move out of the image. Configuration, secrets and resource limits are supplied at deployment, so the same artifact behaves differently in each environment without being rebuilt. This is a benefit and a gap: the image is identical everywhere, while the configuration around it is not, and it needs its own review.

Do separate registries per environment help?

They help with access control rather than verification. A production registry whose push rights belong only to the promotion process makes unapproved content harder to introduce, which is worthwhile. It still proves nothing about what arrived, so the gate at the boundary — signature, provenance, policy — remains the part doing the work.