A build record should capture the source commit, the build instructions, the toolchain and dependency versions, and the hash of every released artifact. With those, you can tell what a release contains and attempt to rebuild it. Store the record next to the artifact, not in someone's memory.
Why a record matters before you are reproducible
Reproducible builds are a goal. A build record is something you can have this week. The reproducible-builds commandments end with an instruction that if you publish binaries, you should take note of your build inputs. Even a team that never reaches identical output benefits, because when a customer asks what is in release 4.2, or a vulnerability is announced, you can answer from a file instead of guessing.
The project's definition of a reproducible build names the same ingredients: source code, build environment and build instructions. A record of those three is a reproducibility recipe, even before you check it.
A practical minimum
| Field | Example content | Why |
|---|---|---|
| Source | Repository, full commit id, tag | Identifies exactly what was built |
| Instructions | Build script path and revision, arguments | Same steps can be rerun |
| Toolchain | Compiler or runtime and build tool versions | Different versions give different output |
| Base image | Image name with digest | Pins the operating system layer |
| Dependencies | Lockfile hash or an SBOM | Shows resolved versions |
| Environment | Locale, timezone, relevant variables | Known sources of variation |
| Outputs | File names and SHA-256 hashes | Lets anyone check an artifact later |
| Run | CI run link, date | For humans investigating |
The reproducible-builds documentation notes that artifacts are verified by bit-by-bit comparison, usually using cryptographic hash functions, which is why output hashes belong in the record.
How to produce it
- Have the build script write one small text or JSON file at the end of every release build.
- Include the fields above, read from the actual environment, not typed by hand.
- Hash the lockfile and the outputs.
- Publish the file with the artifact, in the same release page or bucket.
- Keep it for as long as you support that release.
echo "commit: $(git rev-parse HEAD)"
echo "lockfile: $(sha256sum package-lock.json)"
echo "artifact: $(sha256sum dist/app.tar)"
Keep timestamps out of the artifact itself, but it is fine to put the run date in the separate record, since the record is not part of what you compare.
Records and provenance
Build provenance is the formal version of this. The SLSA specification describes provenance as what entity built the artifact, what process they used and what the inputs were. Its first build level asks just that provenance exists, while higher levels add signing and a hardened platform. A plain record like the one above is a sensible first step towards that, not a replacement for it.
Where Safeguard fits
Safeguard generates SBOMs and scans dependencies, so the dependency line in your record can point to a stored SBOM that is also scanned for known flaws. Free scan: gold.safeguard.sh/scan.
Quick check
Is a build record the same as an SBOM?
No. An SBOM lists components. A build record also holds source, instructions, environment and output hashes. They complement each other.
Who should be able to read the record?
At least everyone who supports the release. Share more widely after deciding what in it is sensitive.
Sources
Last reviewed: 19 October 2026.
