Artifacts & Registries

The pipeline had a package stage that produced “the artifact.” This page is about what that artifact is, why it must be immutable, and the single most important rule in all of CD: build once, promote the same artifact everywhere. Get this right and a whole category of “works in staging, breaks in prod” disasters simply cannot happen.

What an artifact is

An artifact is the concrete, deployable output of your build — the thing you actually ship. Depending on your stack it might be a container image, a .jar, a compiled binary, a tarball, or a Python wheel. For most modern services it’s a container image, and that’s what we’ll use for examples, but the principles are universal.

The defining property of a good artifact is that it is immutable: once built, it never changes. You don’t patch it, you don’t rebuild it “with a small fix” under the same name — if the inputs change, you build a new artifact with a new identity. Immutability is what lets the artifact be a stable unit of truth: when you say “version a1b2c3 is in production,” that string refers to one exact pile of bytes, forever.

A registry is where artifacts live

A registry is the storage-and-distribution service for artifacts. For container images that’s a container registry (Docker Hub, GitHub Container Registry, ECR, Harbor); for language packages it’s npm, PyPI, Maven Central, or a private equivalent. The pipeline pushes a built artifact to the registry; every environment later pulls the very same one. The registry is the shared source of “the bytes,” sitting between build and deploy.

   BUILD ONCE                  PROMOTE THE SAME ARTIFACT
   ──────────                  ─────────────────────────
   build ──► push ──► [REGISTRY] ──► pull ──► staging   ✅ tested these bytes
                          │     ──► pull ──► canary    ✅ same bytes
                          │     ──► pull ──► prod       ✅ same bytes
                      one image,
                      one digest

Tags lie; digests don’t

Here is the subtlety that bites people. Artifacts are usually referenced two ways:

• A tag is a human-friendly, mutable label: app:latest, app:1.4.0. The catch is that a tag is just a pointer — you can re-point app:1.4.0 at a different image tomorrow. latest is the worst offender: it means “whatever was pushed most recently,” which is to say it means nothing reproducible.
• A digest is a content hash, e.g. app@sha256:9f86d0..., computed from the artifact’s actual bytes. It is immutable by construction: change one byte and the digest changes. A digest can only ever refer to one exact artifact, and the same artifact always has the same digest.

	Tag (:1.4.0, :latest)	Digest (@sha256:…)
Stability	Mutable — can be re-pointed	Immutable — fixed forever
Refers to	”Whatever this label points at now”	One exact set of bytes
Safe for promotion?	No — staging and prod could diverge	Yes — guaranteed identical

Never deploy :latest to production

Deploying a moving tag means two environments that both say “:latest” can be running different images, and a redeploy can silently change what’s running with no code change. Pin production to a digest (or a strictly immutable tag like the commit SHA that you never reuse). The whole point of testing an artifact is lost if the thing you tested isn’t provably the thing you ship.

A practical pattern: tag by the immutable commit hash at build time, then resolve and pin the digest for deployment.

# In the pipeline: tag with the commit SHA (never reused) and push.
docker build -t ghcr.io/acme/app:${GITHUB_SHA} .
docker push ghcr.io/acme/app:${GITHUB_SHA}

# Capture the digest the registry assigned — this is the real identity.
docker buildx imagetools inspect ghcr.io/acme/app:${GITHUB_SHA} \
  --format '{{json .Manifest.Digest}}'
# -> "sha256:9f86d0818827...": deploy THIS to every environment

Promotion: move the artifact, not the source

“Promotion” is moving a single artifact through your environments — dev → staging → production — without rebuilding it. This is the rule the overview flagged, and it deserves its own moment, because the naive alternative is so tempting and so wrong: building separately for each environment (“build for staging, then build for prod”). Two builds from the “same” source are not guaranteed identical — a dependency could publish a new patch between builds, a base image could shift, a build tool could update. So the bytes you tested in staging may differ from the bytes you ship to prod, and your testing guaranteed nothing about what’s actually running.

Promotion fixes this by making the artifact the unit that moves. You build once, test that artifact, and promote the identical digest forward. What changes per environment is configuration — database URLs, secrets, replica counts — injected at deploy time via config and secrets, never baked into the artifact. The artifact is environment-agnostic; only the surrounding config differs.

   ❌ rebuild per env                  ✅ promote one artifact
   src ─► build ─► staging             src ─► build ─► [digest] ─► staging
   src ─► build ─► prod (different!)                      └──────► prod (identical)
        bytes may differ                       same bytes + per-env config

This is the book’s thread sharpened to a point. The manual, error-prone step being removed is rebuilding and hoping the result matches — and the implicit, unstated assumption that “same source means same binary,” which simply isn’t true. Immutable, digest-addressed artifacts replace that hope with a guarantee: the exact bytes that passed every gate in the pipeline are the exact bytes serving production traffic. It also makes rollback trivial — the previous good artifact still exists in the registry, unchanged, ready to redeploy by its digest. You’re never reconstructing a past state; you’re re-pointing at one that was never destroyed.

By the numbers — why a digest can’t be faked

“A digest is immutable by construction” rests on a concrete number. A sha256 digest is 256 bits, so it names one point in a space of:

2^256  ≈  1.16 × 10^77  possible digests

Flip a single bit anywhere in the artifact and the hash lands somewhere else in that space, unpredictably (the avalanche effect). To forge an artifact that keeps the same digest, an attacker would have to find a second input hashing to the same value — computationally infeasible at 2^256. That’s what makes app@sha256:9f86d0… a promise rather than a label: the bytes you tested and the bytes you ship are provably identical, not merely identically named.

It actually happened — left-pad and the day npm went dark (2016)

In March 2016 a developer, in a dispute over a package name, unpublished more than 250 of his npm packages — among them left-pad, an eleven-line function that pads a string. Because countless projects (including build tooling for React and Babel) depended on it transitively, builds across the ecosystem suddenly failed to resolve their dependencies. npm took the then-unprecedented step of restoring (“un-unpublishing”) the package to stop the bleeding. The lesson is the dark side of a mutable registry: if the thing you pull can vanish or change, “it built yesterday” guarantees nothing about today. It’s the case for pinning exact versions and treating your dependency supply chain as something to control, not assume.

The architect’s lens

Step back from tags and digests and answer the five questions:

• Why does it exist? Because “same source” does not mean “same bytes” — a dependency patch or a shifted base image between two builds breaks that assumption, so we need one immutable artifact addressed by its content.
• What problem does it solve? “Works in staging, breaks in prod”: build once, push to a registry, and promote the identical digest (@sha256:…) through every environment, so what you tested is provably what you ship.
• What are the trade-offs? You must keep config out of the artifact (inject DB URLs and secrets at deploy time), and you take a hard dependency on the registry as a shared, must-stay-available system.
• When should I avoid it? Rarely for the principle — but pinning to a digest costs you the convenience of a floating tag, so for throwaway local dev a moving :latest is fine.
• What breaks if I remove it? Deploy :latest and two environments can silently run different images; rebuild per environment and your staging tests guarantee nothing — and rollback stops being “redeploy the previous digest, which still exists unchanged.”

Check your understanding

1. What does it mean for an artifact to be immutable, and why is immutability what lets “version X is in prod” be a meaningful statement?
2. Explain the difference between a tag and a digest. Why is :latest dangerous in production?
3. Why can building separately for staging and for production produce different bytes even from the same git commit? What does that do to the value of your staging tests?
4. In the promote-one-artifact model, what does legitimately differ between environments, and how is it supplied?
5. Using the book’s thread, explain how digest-addressed promotion turns “it worked in staging” from a hope into a guarantee — and why it makes rollback easy.

Show answers

1. Immutable means once built it never changes — you never patch or rebuild it under the same name. That’s what makes “version a1b2c3 is in prod” meaningful: the string refers to one exact pile of bytes forever, so the statement is a fact about a specific artifact rather than a moving target.
2. A tag is a mutable, human-friendly pointer (:1.4.0, :latest) that can be re-pointed at a different image later; a digest (@sha256:…) is a content hash, immutable by construction. :latest is dangerous because two environments both saying :latest can run different images, and a redeploy can silently change what’s running with no code change.
3. Two builds from the “same” commit aren’t guaranteed identical — a dependency can publish a patch, a base image can shift, a build tool can update between them. So the staging bytes may differ from the prod bytes, which means your staging tests guaranteed nothing about what’s actually running in production.
4. Only configuration legitimately differs — database URLs, secrets, replica counts — and it’s injected at deploy time via config and secrets, never baked into the artifact. The artifact itself is environment-agnostic.
5. The exact bytes that passed every gate are the exact bytes serving prod, so “it worked in staging” becomes a guarantee rather than a hope — it removes the “rebuild and hope it matches” step. Rollback is easy because the previous good artifact still exists in the registry, unchanged; you re-point at it by digest instead of reconstructing a past state.