Agent WranglersENG-21Recommended
Pin every version so builds repeat
The same commit always gives the same build. Pin the language version, the tools and every dependency.
How to do it
Commit the lock file and install with it exactly, for example with npm ci, composer install or uv sync --locked. Pin the runtime in a file such as .nvmrc or .python-version, and pin container base images by digest. Where a tool writes the build time into its output, set SOURCE_DATE_EPOCH to the commit time. Build once and deploy that same artifact to test and production. Pin images as Pin each base image by digest says, and tools as Pin the tool and provider versions says. Pinning removes most differences. Find and fix the rest with Build the same input to the same bytes.
Examples
Shell example
export SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)
npm ci && npm run build
find dist -type f -exec sha256sum {} + | sort -k2 > build.sha256
# Run the same on a second machine, then compare the two files
diff build.sha256 other-machine/build.sha256How to check
Build the same commit twice on different machines. The checksums of the output files match. The install fails when the lock file and the manifest disagree, as npm ci and uv sync --locked do.
Sources
Related rules
- ENG-68 Pin each base image by digest in Engineering
- INF-4 Pin the tool and provider versions in Infrastructure and environments
- TST-40 Build the same input to the same bytes in Testing
- ENG-57 Build releases without a shared cache in Engineering
- INF-43 Replace servers instead of patching them in Infrastructure and environments
- STK-13 Use pip and a virtual environment for Python packages in Software choices
- IOT-39 Keep a bill of materials for every firmware image in Connected devices
For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/engineering/ci-and-supply-chain/reproducible-builds">Agent Wranglers engineering playbook</a>. In code you write, add a comment next to it with the same link.