Project challenges / verified progress
Beacon: ship it without fear

The engineering notebook

Move the same bits

Why should environments receive the same image digest instead of rebuilding?

Loading Vault account...
Protect the artifact

Step 01 of 06

Understand the idea

If you rebuild an application for each environment, the resulting images may differ. Promotion moves the same image from testing to production. An immutable digest identifies that exact image so you can check it has not changed.

ONE DIGEST THREE GATESpromotion pathBuildsha256 digestonceDevauto deployminutesStageapprovalhoursProdrelease gatemanual
Promotion spends time on approval and observation, not recompilation. If staging and production use different digests, staging did not test the thing users received.
Step 01

Key technical ideas

A digest is the artifact fingerprint

An OCI digest is a hash of the image manifest. If one byte changes, the digest changes. Tags are pointers that can move. Promotion records the digest because scanners, signatures and deployments can all agree on it.

Environment config changes around the artifact

Development may use one replica and production five. Those differences belong in overlays, secrets and environment variables. They do not require rebuilding Beacon. A binary that needs recompilation to know where it runs is smuggling deployment policy into the artifact.

Approval gates are about permission

GitLab environments can require reviewers before a job targets production. That gate should authorize a known digest. If the job rebuilds after approval, the reviewer approved yesterday's evidence for today's unknown artifact.

Shipping one sealed crate
# Start a pipeline with the exact image digest to promote.
glab ci run -b main --variables "PROMOTION_DIGEST:sha256:91b4d142e32f8a5d3c2c9f1f4b8a7d6e5c4b3a291817161514131211100f0e0d"
glab ci list --per-page 1

The label helps humans, but the seal proves identity. Repacking at each stop would make the first inspection irrelevant.

Tags and digests serve different jobs

IdentifierCan moveGood for

latest tag

Yes

Local convenience

Version tag

Should not

Human release name

Git SHA tag

Can be overwritten

Trace to source

Digest

No

Promotion and signing

Technical terms used at work

  • Digest — Immutable OCI identifier for an image manifest, usually beginning with sha256:.

  • Tag — A human-friendly registry pointer that can be moved unless policy prevents it.

  • Promotion — Authorizing one already-built artifact to run in a later environment.