---
title: "Pin every version so builds repeat · Agent Wranglers"
url: https://agentwranglers.se/playbook/engineering/ci-and-supply-chain/reproducible-builds
id: ENG-21
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 1013
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Pin every version so builds repeat

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [CI and supply chain](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: ENG-21
- Level: Recommended
- Chapter: [CI and supply chain](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain.md)
- Rule: The same commit always gives the same build. Pin the language version, the tools and every dependency.
- 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.
- How: 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](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain/pinned-base-images.md) says, and tools as [Pin the tool and provider versions](https://agentwranglers.se/playbook/infrastructure/infrastructure-as-code/pinned-provider-versions.md) says. Pinning removes most differences. Find and fix the rest with [Build the same input to the same bytes](https://agentwranglers.se/playbook/testing/output-comparison/same-input-same-bytes.md).

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Shell example

```sh
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.sha256
```

## Sources

- [Reproducible Builds: Definitions](https://reproducible-builds.org/docs/definition/)

## Related rules

- ENG-68 [Pin each base image by digest](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain/pinned-base-images.md) in Engineering
- INF-4 [Pin the tool and provider versions](https://agentwranglers.se/playbook/infrastructure/infrastructure-as-code/pinned-provider-versions.md) in Infrastructure and environments
- TST-40 [Build the same input to the same bytes](https://agentwranglers.se/playbook/testing/output-comparison/same-input-same-bytes.md) in Testing
- ENG-57 [Build releases without a shared cache](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain/no-cache-in-release-builds.md) in Engineering
- INF-43 [Replace servers instead of patching them](https://agentwranglers.se/playbook/infrastructure/servers/immutable-servers.md) in Infrastructure and environments
- STK-13 [Use pip and a virtual environment for Python packages](https://agentwranglers.se/playbook/stack/languages-and-runtimes/pip-and-venv.md) in Software choices
- IOT-39 [Keep a bill of materials for every firmware image](https://agentwranglers.se/playbook/connected-devices/firmware-updates/firmware-sbom.md) in Connected devices

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/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.

- Next: [Pin each base image by digest](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain/pinned-base-images.md)
- [CI and supply chain](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain.md)