Make a Build Reproducible
If two builds of the same commit differ, a checksum in a release note proves nothing and every cache hit is luck. Determinism must be shown, not assumed.
Procedure
- Measure the drift before fixing it. Build twice and diff the trees:
diffoscope build-a.tar.gz build-b.tar.gz | head -60Build once locally and once in a clean container to expose environment leakage. - Pin every input. Use
FROM debian@sha256:<digest>, notdebian:stable. A floatingnode:20tag is not a pin. - Set
SOURCE_DATE_EPOCHto the commit time so embedded dates are stable:export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct) - Normalise the shell:
export LC_ALL=C TZ=UTC PYTHONHASHSEED=0. Sort any generated file underLC_ALL=C sort -u. - Strip build paths. Go:
go build -trimpath -ldflags="-buildid=" -o out. C: add-ffile-prefix-map=$PWD=.. Rust: setremap-path-prefixinsideRUSTFLAGS. - Make archives deterministic — tar records mtime, owners and readdir order:
tar --sort=name --mtime=@$SOURCE_DATE_EPOCH --owner=0 --group=0 --numeric-owner -czf out.tgz dir/For zip:zip -X -r out.zip dir/and reset each entry's mtime to the epoch. - Remove counters and host data.
git describe --dirtyembeds working-tree state; usegit rev-parse HEAD. Drop build counters and hostnames. - Rebuild on a second machine and compare digests:
sha256sum a/out.tgz b/out.tgz.
Pitfalls
- Signing, SBOM and packaging steps re-add a timestamp. Hash and sign the built artifact in a separate pass, then never rebuild it.
apt-get installin the Dockerfile pulls unpinned versions; pin via a committed lock or a hermetic mirror.- Python
.pycfiles embed absolute source paths. Build withPYTHONDONTWRITEBYTECODE=1. - Parallel linkers can reorder object files. Emit linker inputs as a sorted list.
- A cache that keys on branch name, not content, hides drift until release day.
Verification
./build.sh && cp -r dist dist1 && rm -rf dist && ./build.sh && \
diff -r dist dist1 && echo REPRODUCIBLE
diff -r prints nothing and exits 0 on a match. For a single binary, compare sha256sum dist/app dist1/app and assert equal.
Report: "Two builds of match byte-for-byte; after setting SOURCE_DATE_EPOCH and deterministic tar flags, diffoscope reports no differences."