Sealed Checksums for Byte-for-Byte Reproducible Builds

Check out git commit c4a1e9 from four months ago. Run your standard packaging command. Compute the SHA-256 hash of the resulting .tar.gz and compare it against the binary archive released to your production servers.

The hashes will almost certainly differ.

Your source tree is identical. Your dependency lockfile has not changed. The compiler version is pinned. Yet checksum verification fails. When two independent builds of the same commit yield different bit sequences, you cannot prove that the binary deployed on your infrastructure was derived exclusively from the source code you audited.

Supply chain integrity requires byte-for-byte reproducible builds. Achieving them means eliminating every piece of ambient machine state that packaging tools inject by default.

Where Non-Determinism Leaks into the Archive

When release archives diverge, the underlying application logic is rarely the cause. The entropy enters during archive creation. Standard archiving tools like tar and zip record ambient host properties that have nothing to do with your code:

1. File Modification Timestamps (mtime): Git does not preserve file timestamps on clone; it sets them to the local checkout time. Every fresh checkout on a CI runner stamps files with the current clock time.
2. File Ordering: Filesystem directories are unordered sets. Archiving utilities read directory entries in inode order, which varies across disks, operating systems, and filesystem drivers.
3. User and Group IDs: Archives record the local UID and GID of the process that created them. An artifact packed by a CI runner running as UID 1001 will not match one packed by a developer running as UID 1000.
4. Compression Headers: Default gzip headers store the original filename and the timestamp at which compression ran.

Compilers and linkers introduce similar variance by recording absolute build paths in debug symbols or embedding current dates via standard macros. If two runs capture different local environments, the resulting build artifacts diverge at the binary level.

Enforcing a Bit-Identical Pipeline

To produce deterministic software artifacts, the build pipeline must be treated as a pure function: the same source tree and the same toolchain must produce the exact same byte stream every time.

First, clamp all file timestamps using SOURCE_DATE_EPOCH. This standard defines a fixed UNIX timestamp—typically the timestamp of the last Git commit—used in place of the current system clock during compilation and packaging. We previously covered the mechanical details of this in our guide on eliminating timestamp drift in binary release checksums.

Second, sort the input file list explicitly before passing it to the archiver, and normalise all ownership metadata to root.

Here is a minimal, portable pipeline for creating a byte-for-byte identical tarball from a dist directory:

## Set timestamp to the commit time of HEAD
export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)

## Sort file list by byte order, clamp mtime, zero out ownership
find dist/ -type f -print0 \
  | LC_ALL=C sort -z \
  | tar --null -T - \
    --create \
    --file=release.tar \
    --mtime="@${SOURCE_DATE_EPOCH}" \
    --owner=0 --group=0 --numeric-owner \
    --mode=go=rX,u+rw,a-s

## Compress without embedding timestamp or original filename
gzip -n -9 < release.tar > release.tar.gz

## Compute archive checksum
sha256sum release.tar.gz

Running this pipeline across separate hosts against the same commit produces identical SHA-256 digests. Once ambient file timestamps, sorting variance, process metadata, and header timestamps are stripped, the output is bound entirely to the source repository state.