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.
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.
# 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 1The label helps humans, but the seal proves identity. Repacking at each stop would make the first inspection irrelevant.
Tags and digests serve different jobs
| Identifier | Can move | Good for |
|---|---|---|
| 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.
