How do you make a shipped release traceable to the exact commit it was built from?

## Provenance is a property of the path, not of the name A release name fixes one commit, which is necessary and nowhere near sufficient. Between that commit and the bytes running in production there is a build, and every unrecorded input to that build is a gap in the story. The goal is that anyone holding a running artefact can answer, months later and without asking a person, **"which source produced this, and can I rebuild it?"** A concrete failure makes the shape obvious. A podcast hosting service ships a transcoder release, 4.11.3, that serves 1,286 hosted shows. Two weeks later a partner reports silent audio on a narrow class of uploads, and the fix has to reach a hardware player whose delivery date cannot move — 9 days out, with no possibility of slipping. The team discovers that 4.11.3 was cut from a laptop that carried three uncommitted edits, and that the pipeline log naming the build inputs expired after 30 days. They can see the tag. They cannot rebuild what shipped. Most of the 9 days goes on reconstruction rather than on the fix. ## The chain that has to hold 1. **One commit, one immutable release name.** The name is the release identity, and it never moves after publication. 2. **Build from that name, in a pipeline.** A build cut on a workstation carries that machine's state as an invisible input. An automated build from the named commit is the only version anyone can repeat. 3. **Refuse to build a release from a dirty working copy.** If uncommitted edits are present, the identifier the build stamps is describing source that differs from what was compiled — the record is not merely incomplete, it is false. 4. **Stamp identity into the artefact.** The version and the commit identifier belong in the artefact's own metadata and in whatever the running process reports about itself. Identity that lives only in a pipeline log dies when the log's retention window closes. 5. **Pin what the source does not contain.** Same source plus floating dependency ranges is not the same build. Commit the resolved dependency set at the tagged point and name the toolchain version explicitly. 6. **Store the artefact immutably.** A published version's bytes are never overwritten; a fix is a new version, exactly as a corrected release is a new number rather than a moved name. ## Provenance versus bit-for-bit reproducibility These are routinely conflated in interviews, and separating them is most of the answer: | | Provenance | Bit-for-bit reproducibility | |---|---|---| | Claim | I know which source produced these bytes | Rebuilding that source yields identical bytes | | Needs | An immutable name, a clean build, a stamped identity | Normalised timestamps, paths, ordering, pinned toolchain | | Cost to reach | Days of pipeline work | Months, and constant vigilance | | Buys you | Debugging, rollback, audit, incident response | Verification that a binary was not tampered with | Almost every team needs the left column, and only some need the right. A senior answer says so plainly instead of promising byte-identical rebuilds it has never measured. Two rebuilds of the same commit differing in bytes is **not** a provenance failure — it means an input outside the source varied, which is expected until it is deliberately controlled. ## Where the identity has to be readable The test is a specific one: an on-call engineer, woken at 03:00, looking at a misbehaving instance, with no access to whoever cut the release. They must be able to get from that instance to a version and a commit identifier. That rules out identity that exists only in a build log, a chat message, a deployment ticket or somebody's memory. It rules in artefact metadata and a self-reported version from the running process. The same test applies to the artefact store: given a version, you must be able to retrieve the exact bytes that were published, not a rebuild that happens to carry the same number. ## Rehearse it, or you do not have it Provenance is a recovery capability, and untested recovery capabilities do not exist. The cheap drill: - Pick a version shipped three to six months ago, chosen at random rather than the one most recently touched. - Give it to an engineer who did not cut it, with only the artefact and the repository. - Ask them to rebuild it and account for any difference from the published bytes. The first run of that drill reliably finds something: a dependency that no longer resolves to what it did, a toolchain that was upgraded on the pipeline host without a record, an identifier stamped in a format nobody can map back, or a release that turns out to have been cut by hand during a quarter busy enough — 118 stories delivered — that nobody remembers doing it. Finding those during a drill costs an afternoon. Finding them during an incident costs the incident.