artifact-management

Artifact Management

An artifact is the one thing that should never be ambiguous in a delivery pipeline: given a version or digest, everyone — CI, CD, an engineer debugging an incident six months later — should be able to retrieve the exact same bytes. The moment an artifact can be overwritten, rebuilt with a different result, or referenced by a mutable tag like latest, every downstream promise (this is what passed CI, this is what's in staging, this is what's in prod) becomes unverifiable.

If you can't prove two environments are running the exact same artifact, you can't actually debug the difference between them.

An artifact, once built, is immutable — every later stage promotes it, none of them rebuild it.

1. Build once, promote the same bytes everywhere

Rebuilding "the same" artifact for staging and again for production is the single most common artifact-management mistake, because non-determinism anywhere in the build (unpinned dependency, timestamp embedded in the binary, compiler nondeterminism) means the two builds aren't actually the same thing, and you've now tested one and shipped another. Build exactly once in CI, publish it with an immutable identity, and every later environment pulls that identity — promotion is a metadata operation (retag, update a manifest, flip a pointer), never a rebuild.

• CI builds it once, produces a content-addressed digest.
• Staging and production reference that digest, not a rebuilt equivalent.
• Promotion changes only which environment points at the digest, never the bytes themselves.

Done when: you can diff the digest running in production against the digest that passed CI and they match exactly.

2. Version with immutable, content-derived identifiers

Mutable tags (latest, stable, even a branch name) are conveniences for humans, not identities a system should depend on — the tag latest points at something different every time someone pushes. Use a content digest (sha256) or an immutable version (a semver tag that's never reused, or the git SHA) as the actual reference everywhere automation touches; reserve human-friendly tags as an alias layered on top, never as the source of truth for a deploy.