The immutable identity principle — every artifact has a content-addressed identity

An artifact is immutable when the bytes that compose it cannot change without the artifact’s identity changing too. The principle is simple but its consequences reshape every other practice in this part: a tag is a pointer, a digest is an identity, and only the digest survives promotion, rollback, and audit. Once the bytes change, the digest changes, and the artifact is no longer the artifact — it is a different artifact that happens to share a tag.

What identity means for an artifact

Identity is the property that lets two observers agree they are looking at the same thing. A filesystem path is not an identity: a path is a location, and the bytes at that location can be replaced without the path changing. A name is not an identity: a tag like :v3.2.7 can be reassigned, and the tag does not know the difference. An identity is something the contents themselves dictate, independent of where the artifact lives or what it is called.

flowchart LR
    A["Source bytes"] --> B["SHA-256 over contents"]
    B --> C["Content address — immutable"]
    D["Path or tag"] --> E["Independent of bytes"]
    C --> F["Same bytes, same address"]

The function that derives an identity from contents is called a content-address function. SHA-256 is the canonical choice for container registries: the same input bytes always produce the same 256-bit digest, and producing two different inputs with the same digest is computationally infeasible. The registry cannot “reassign” a digest; the registry can only confirm that the bytes uploaded match the digest claimed. If they do not match, the upload is rejected.

Mutable reference versus content address

The difference matters because of what each can answer. A path can answer “where is the artifact?”. A tag can answer “what name did the team give it?”. A content address can answer “what is it?” — and the answer survives relocation, renaming, re-tagging, and the lifetime of the uploaders.

The shift in question framing is subtle but decisive. The question “where is the artifact?” assumes a stable location; the question “what is the artifact?” assumes a stable identity. Production systems need stable identities, not stable locations, because identities travel through environments and locations do not. A digest that survives the move from staging to production is the contract that makes the deployment auditable; a tag that gets reassigned on every push is not.

Why mutability is a contract violation

When a tag can be reassigned, every consumer of that tag has an implicit contract with whoever holds the push credential. The contract is: “when I read :latest, I expect to see the most recent build”. The contract is silent on who decides what “most recent” means. In a single-team repository the contract often holds. In a multi-team registry, or a registry whose push credentials are compromised, the contract is a hole that whoever pushes last walks through.

The fix is not “be more careful with tags” — the fix is to separate the question of identity from the question of naming. Identity is the digest; naming is the tag. The two are layered: the digest is the answer, the tag is the handle. A team that pins by digest treats the tag as a hint and the digest as the contract.

Identity over time

The production rule that follows from the immutable identity principle is: an artifact is named once, at build time, by the digest the build produced. The tag is decoration; the digest is the contract. Every promotion, every rollback, every audit answer points at the digest, not the tag. A team that cannot name the digest of what is running in production cannot answer “what is running in production”.

Production discipline

1. Tag the artifact at build time by its digest. The build computes the digest; the pipeline records it; the deployment references it.
2. Never trust a mutable reference for production. A tag is mutable by definition; a tag is a development convenience, not a production contract.
3. Treat the digest as the audit answer. “What is running?” is answered by the digest, not the tag, not the path, not the build number.

Cross-course references

• Git, CI/CD & GitOps — Part XLIV (Artifacts) establishes the artifact model that immutability extends.
• Terraform for Production Sysadmins — Part XIX (State Locking) applies the same identity principle to Terraform state versions.
• Linux for Production Sysadmins — Part XII (RepoSecurity) covers apt/dnf package signing, the OS-level analogue of content addressing.

Quiz