One Version, One Artifact

Why this matters

Version 2.4.1 passes all gates on Tuesday; on Thursday a customer reports a bug that 2.4.1 cannot contain, because Thursday's 2.4.1 was rebuilt from a newer commit with the same tag. Movable tags plus per-environment rebuilds mean the version string is a rumor. Incident response starts with which bytes are running, and a reused name makes that question unanswerable.

Concepts

Build once is the whole doctrine. The pipeline compiles, bundles or images exactly one artifact, stamps it with an immutable identifier (content digest plus a human version), and every later stage tests, scans and deploys that identical file or image. Rebuilding per environment reintroduces untested combinations: different dependency resolution, different timestamps, a different compiler. Promotion moves bytes; configuration moves separately per environment, exactly as M05 lesson 3 demands for images.

Names must be injective: one name, one byte set, forever. Semantic versions for humans plus the digest for machines; tags are pointers that humans move, digests are identities nobody can. Never overwrite a published tag or re-upload different bytes under one version: registries and caches remember, and two machines pulling one name get different software. If a build is bad, mint a new version; history is append-only.

Caches speed builds; they must never define identity. Dependency and layer caches key on lockfiles and content hashes, never on branch names or latest, because a poisoned or stale cache entry then silently becomes the product. The artifact's identity comes from its own digest computed after the build, independent of which cache hits occurred. Lab L18 shows a wrong cache key promoting stale code under a fresh name; lab L17 shows two byte sets sharing one version and the incident that follows.

Provenance records the lineage: source commit, build definition version, base image digest, dependency locks, gate verdicts. Signing (Sigstore, registry signatures) lets any environment verify the artifact came from the real pipeline before running it. Verification at deploy time closes the loop the pipeline opened at build time.

Worked example

Staging and production run different bytes under version 2.4.1. The trail:

$ crane digest registry/app:2.4.1 sha256:9f2a... (pulled Monday) $ crane digest registry/app:2.4.1 sha256:51be... (pulled Thursday, tag moved)

Expected reading: the tag was overwritten by a rebuild, so Monday's certified bytes and Thursday's running bytes differ while the name stayed still. The repair freezes tags (registry immutability rules), promotes by digest, and shows every environment resolving the same sha256. Verify by pulling the digest in two environments and comparing: identical bytes, one name that now tells the truth. Lab L17 replays the movable-tag incident in miniature and requires the append-only fix.

The common wrong move

latest as a deployment reference, or environment-suffixed rebuilds (app-prod built separately from app-staging). latest resolves differently per pull, so rollbacks restore unknown bytes; separate builds mean production never ran the tested artifact. Pin digits, promote digests, and let latest be a billboard, never an address.

Lab and next step

Lab L17 stages the two-bytes-one-name incident and requires the immutable fix with digest proof. Next, lesson 4 locks down the pipeline's own privileges: credentials, permissions and the cache as an attack surface.