Source-Date-EPOCH Overrides for Reproducible Builds

Timestamp variance breaks audit trails

Your team can rebuild a library from source, but the resulting archive differs from the one stored in the release registry. The difference is a few bytes of embedded timestamps. Those bytes change on every run, even when the source tree and compiler flags are identical. Auditors flag the mismatch as a breach of the build provenance policy. The failure mode is timestamp variance.

SOURCE_DATE_EPOCH removes the hidden clock

POSIX defines the SOURCE_DATE_EPOCH environment variable as a single integer representing seconds since the Unix epoch. When it is set, compliant tools replace any runtime‑generated timestamp with that value. The result is a repeatable artifact: the same source, the same flags, the same SOURCE_DATE_EPOCH produce byte‑for‑byte identical archives.

A concrete example with tar shows the effect:

export SOURCE_DATE_EPOCH=1700000000
tar --mtime="@${SOURCE_DATE_EPOCH}" -czf lib.tar.gz src/

The --mtime flag forces the archive header to use the supplied epoch. Without the flag, tar would embed the current time, breaking reproducibility. The same pattern applies to zip, jar, and most compiler toolchains that honour the variable.

Wiring the variable into a CI pipeline

Pick a fixed epoch for the release, for example the commit timestamp of the tag that marks the release. Export the variable early in the pipeline, before any build step runs. In a GitHub Actions workflow you might write:

- name: Set reproducible timestamp
  run: echo "SOURCE_DATE_EPOCH=$(git log -1 --format=%ct $GITHUB_REF)" >> $GITHUB_ENV

Verify that each tool in the chain respects the variable. Not all compilers do. gcc respects SOURCE_DATE_EPOCH for the __DATE__ and __TIME__ macros only when -frandom-seed is also supplied:

gcc -frandom-seed="${SOURCE_DATE_EPOCH}" -c src/foo.c

Run the SHPBL certification harness on the produced archive. The harness is available to Practitioner‑tier customers; it is not part of the free repository evaluation. It records a verdict of CERTIFIED, PROVISIONAL, INCONCLUSIVE, or FAILED depending on the artifact and the exercised contract. A CERTIFIED verdict indicates that the archive matches the published checksum; other outcomes signal a limitation in the harness or a missing reproducibility guarantee.

SHPBL provides a model‑independent library and a certification harness

The library contains no runtime model calls, and the harness can be invoked via the HTTP API, the TypeScript SDK, or the offline edition. Details are in the SHPBL documentation.

Monday’s concrete step

Open your CI definition file. Add a step that extracts the tag’s commit timestamp and writes it to SOURCE_DATE_EPOCH. Then run a single build and compare the resulting archive’s checksum to the one stored in your release registry. If they match, you have achieved a reproducible build for this release. If they differ, audit the toolchain for missing SOURCE_DATE_EPOCH support and add the necessary flags.

Implementing this change eliminates timestamp variance, restores auditability, and aligns your pipeline with a repeatable‑artifact posture.