Pin and Verify a Toolchain
"Works on my machine" is usually "works with my compiler". Pin the exact toolchain in the repo so CI, laptops and release builders agree, and verify what you download.
Procedure
- Pin per language in the file its manager reads on checkout:
- Node:
.nvmrc(orengines+packageManagerwithcorepack), commit the exact version20.11.1. - Python:
.python-versionfor pyenv, or apython_requiresplus a locked interpreter in the CI image. - Rust:
rust-toolchain.tomlwithchannel = "1.78.0"and the components you need. - Go: the
toolchain go1.22.3directive ingo.mod. - Multi-tool repos:
.tool-versionsformise/asdf, one line per tool.
- Node:
- Enable corepack so Node package managers are pinned too:
corepack enable && corepack prepare pnpm@9.1.0 --activate. - Do not trust a
curl | bashinstaller. Download the artifact, then verify its checksum or signature:curl -fsSLO https://example.org/tool-1.2.3.tar.gz && \ echo "<sha256> tool-1.2.3.tar.gz" | sha256sum -c - - Fetch the expected checksum from a signed source, not a URL on the same CDN that served the binary.
- Re-pin in a dedicated PR; treat a toolchain bump as a dependency change requiring a full CI run, not a drive-by edit.
- Make CI install from the pin:
mise installrespects.tool-versions;rustuprespectsrust-toolchain.toml;setup-nodereads.nvmrc. - Record the installed versions as a build artifact so a failure can be attributed:
node -v && rustc -Vv && go version | tee toolchain.txt.
Pitfalls
- Pinning
latestor a major-onlynode@20defeats the purpose; patch versions change behaviour. rust-toolchain.tomlwithoutchannel =set exactly lets rustup pull the current stable on each machine.- A checksum file fetched over the same connection it is meant to authenticate adds no security.
- Pinning in CI but not for developers means CI catches a version skew only after a push.
- A
packageManagerfield withoutcorepack enableis advisory; CI will still use whatever npm happens to be installed.
Verification
test "$(node -v)" = "v$(cat .nvmrc)" && rustup show active-toolchain | grep -q 1.78.0 && \
cat toolchain.txt
Each tool's runtime version equals its pin file on a fresh checkout, and the recorded toolchain.txt for the release matches the CI job's.
Report: "Toolchain pinned (node $(cat .nvmrc), rust 1.78.0, go 1.22.3); installer checksum verified; fresh CI and local installs report identical versions."