Blog
Stop Terraform toolchain drift with mise and Renovate: one pinned file per repository
How thirty Terraform module repositories moved to one pinned toolchain, with Renovate keeping the pins current and CI carrying the same ones

At a client, the platform team I work in maintains about thirty reusable Terraform module repositories. Each needs five or six command-line tools at specific versions, and until this year every laptop and every CI job found its own way to install them. Between May and September we moved the fleet to mise, a dev-tool version manager. Each repository now commits a .mise.toml. Renovate opens the version bumps, our Copier template seeds the file, and the CI tooling image installs its tools with mise from pins of its own. This post covers the choice, the setup that holds at fleet scale, and the traps worth knowing before a rollout of your own.
The problem
A Terraform repository needs more than Terraform. Its lint and test targets may also call Terragrunt, the tflint linter, the TruffleHog secret scanner, the pre-commit hook runner, and sometimes checkov or commitlint. They all change behaviour between releases, so a check can pass on a laptop and fail in CI.
Each tool's version lived somewhere different. Terraform and Terragrunt came from tfenv, tgenv, tfswitch or tgswitch, single-tool version managers, depending on who set up the laptop. The rest came from Homebrew or an install script, and CI installed its own defaults. Nothing moved unless someone remembered to bump it, and across thirty repositories nobody remembers consistently.
The trigger was small. In May a teammate regenerated a module's documentation locally, pushed, and CI failed its docs check. Three versions of the same tool were in play: one on the laptop, one on the CI runner, one in the other GitHub instance we were migrating from. Another teammate had filed a ticket about that mismatch a fortnight earlier.
Before that, in December, a plan difference had the squad pasting Terraform and Terragrunt versions and binary checksums from their machines into the chat to find out who had what. Other teams were adopting Nix, which our developers considered too heavy for the job, and two teammates had been running mise for months without a complaint.

One .mise.toml per repository: the template seeds it, Renovate bumps it, the CI image carries the same pins.
The goal was one committed file per repository that laptops pick up without a manual step and a bot keeps current.
Why not direnv or aqua
The first candidate was direnv, which loads a .envrc file when you enter a directory. A bash script in it downloaded the pinned binaries. It works, but it is a page of bash per repository with no checksum verification, direnv asks for direnv allow again whenever the file changes, so every version bump becomes a prompt on every laptop, and Renovate can only reach those pins through custom regex managers.
The second candidate, and the one I proposed, was aqua, a declarative version manager for CLIs. aqua pins tools in YAML, verifies checksums, can check signatures and provenance where its registry defines them, and has a first-party Renovate preset. The team weighed the size of its community, about 2,000 GitHub stars against about 30,000 for mise, and asked who would maintain it years from now. The two teammates already on mise had the stronger argument: it worked for them. We settled on mise a week later.
We also looked at asdf, proto, Hermit, Nix with devenv, and dev containers. asdf lacks built-in verification, proto leans towards JavaScript tooling, Hermit's registry is small, Nix has a steep learning curve, and dev containers add a container to every workflow.
Why mise
Three things decided it:
- Renovate has a native mise manager. It finds
.mise.tomlon its own, with no custom rules. - It reads asdf's
.tool-versions. Repositories already on asdf migrate without edits. - It keeps the aqua work. A backend, in mise's terms, is the source a tool installs from. The aqua registry is one, and on macOS and Linux all five core tools below resolve through it by default. Anything else in that registry can be pinned with an
aqua:prefix.
A representative file follows. Each repository lists only what its lint and hooks run, and mise ls shows where every pin comes from, the repository file or the developer's own global config.
[tools]
terraform = "1.12.2" # kept identical to CI
terragrunt = "0.77.5"
tflint = "0.55.1"
trufflehog = "3.97.4"
pre-commit = "4.6.0"
# needs an explicit backend
"aqua:mszostok/codeowners-validator" = "0.7.4"
"npm:@commitlint/cli" = "21.0.2"

mise trust, then mise ls in a module: two tools still missing, two coming from the global config, the rest pinned by the repository file.
GitHub tokens on an enterprise laptop
mise installs most of these tools from GitHub releases, so it calls the GitHub API. It uses the first token it finds, in this order: MISE_GITHUB_TOKEN, GITHUB_API_TOKEN, GITHUB_TOKEN. Developers at the client export GITHUB_TOKEN for the company's GitHub Enterprise instance, which internal tooling needs. mise sends that token to api.github.com and gets 401 Unauthorized. An anonymous request would work, but mise does not fall back.
A fallback to anonymous requests after a 401 looks like the obvious fix, and we proposed it upstream. The maintainer's position is that unauthenticated requests are not a good default and that the token guide is the supported path, so the pull request was closed. An empty MISE_GITHUB_TOKEN does not help either: mise treats it as unset and falls through to GITHUB_TOKEN.
The supported setup is a separate github.com token in MISE_GITHUB_TOKEN, which wins over GITHUB_TOKEN. A fine-grained personal access token with read access to public repositories and every permission at "No access" is enough. It grants nothing an anonymous caller lacks, and it raises the API limit from 60 to 5,000 requests per hour. Give it a finite expiry and expect a 401 on the day it lapses: a token nobody rotates is a token nobody remembers exists.
# ~/.zshrc
export MISE_GITHUB_TOKEN="github_pat_..." # zero-permission github.com token
eval "$(mise activate zsh)"
Renovate on GitHub Enterprise needs the same kind of token, in RENOVATE_GITHUB_COM_TOKEN. Newer mise releases call GitHub less often, but the token order still applies.
Trust is code execution
A mise file can do more than pin versions. It can set environment variables from templates, define tasks, and declare hooks that run a command when your shell enters the directory. Until you trust a file, entering its directory does not run its hooks or apply its environment without asking. Recent releases skip the prompt for a file that holds only plain version pins, and treat explicit commands such as mise install as consent.
cd some-module
mise trust # once per repository
mise install # every pinned tool
mise use terraform@1.8.0 # edits the pin in .mise.toml
mise shell terraform@1.7.0 # this shell only
Earlier releases asked for trust on every file, and trusting thirty repositories one by one guarantees stragglers. trusted_config_paths, set in your personal global config, trusts every file under a directory, including repositories you clone later.
# ~/.config/mise/config.toml, never committed
[settings]
trusted_config_paths = ["~/src/work"]
Read that line as permission for any .mise.toml under the path to run code when you cd into it. The trust follows the path, not the content. A merge gate protects the default branch, but it does nothing for the pull request branch you check out to review. Point the setting only at repositories you own, never at a folder of third-party clones, and never at /. Our default is per-repository trust; blanket trust waits for a team policy on hooks and tasks.
Opt-in and reversible
A .mise.toml does nothing on a machine without mise, so developers who never install it keep their Homebrew or tfenv binaries. During the backfill the file sat next to .terraform-version, so tfenv users saw no change. Leaving means deleting the activation line from your shell profile. That made mise a recommended default rather than a mandate, and it coexists with the Nix setups other teams run.
Seeding the file with Copier
Copier is a project template tool that can also update the projects it generated. Our module template already updated its projects through Renovate, a teammate's design from April, and mise rode on it. The template gained a .mise.toml with a minimal baseline: Terraform, TruffleHog and pre-commit. New modules get it at generation. Existing modules get it through template-update pull requests, which Renovate's Copier manager opens when the template releases.
The template lists the file under _skip_if_exists. Copier creates it when missing and never overwrites it afterwards, so a repository that adds tflint or commitlint keeps them through every template update. The template owns the first version of the file, and Renovate owns the pins after that.
A template release that touches CI needs its workflow change in the same release. The first release that carried the file reached the child modules' deploy pipeline before their workflows were ready for it, an engineer from another team spotted the failures, and eight fix pull requests closed the gap within the week. The template fix itself then waited in a pull request long enough for the stale bot to close it, so the September rollout started by reviving it. Give a fix in flight a second owner before anyone goes on holiday.
Renovate owns the pins
Our template used to carry custom regex managers for pins the mise manager did not resolve at the time, TruffleHog among them. On Renovate 44 the native manager resolved every pin we had, so the regex managers could go.
The order mattered. With both active, Renovate would find those pins twice and open duplicate pull requests in every repository. So the template release that removed the regex managers landed first, and only then did our self-hosted Renovate image move to 44. We tried the new image on one repository before dispatching Renovate across the fleet.
That dispatch opened 91 pull requests across 32 repositories in three waves, reviewed and merged by hand in one afternoon. Some of those TruffleHog bumps had sat open since July. The next day automerge went live, and that day's 85 pull requests merged themselves without a human touching them.
Automerge means Renovate merges a pull request itself once the required checks pass. The rules were existing team work, and the branch-protection settings let the bot merge when the CI gate check is green. Switching it on across the fleet exposed two repositories whose CI job had a different name: the required check never reported, and their pull requests waited until the names were fixed. The same two had been generated from a personal clone of the template, so template updates had never reached them either, and nothing had failed to say so.
The rules split by risk. Template updates and minor or patch GitHub Actions bumps merge themselves. Tool pins and Terraform providers wait for a person. For tool pins a green check proves little, because CI does not read .mise.toml yet and never runs the new version.
{
"extends": ["config:recommended"],
"packageRules": [
{ "matchManagers": ["copier"], "automerge": true },
{
"matchManagers": ["github-actions"],
"matchUpdateTypes": ["minor", "patch"],
"automerge": true
},
{
"matchManagers": ["mise", "terraform"],
"matchDepTypes": ["tools", "provider", "required_provider"],
"automerge": false
}
]
}
After the switch we let the setup settle for a week and turned follow-ups into tickets instead of more pull requests, which is how the behaviour of unattended runs became visible.
Unattended runs surface concurrency. Two Renovate pull requests in one repository ran Terraform tests against the same test state at the same time. The reusable workflows now serialise test jobs with a lock timeout, so the second run waits for the state lock instead of failing, and we forced the overlap on two throwaway pull requests before releasing the fix.
Go and npm bumps need their lock files. Letting Renovate install its tools at run time broke the Copier updates, so the working setup preinstalls the binaries in the Renovate image, and the lock files ship with the bumps.
Two more things only show up at fleet scale. Some unattended test runs died halfway through with no error worth the name: the runner container had a 4 GB memory cap, and the test job now runs in a 16 GB job container. And a misconfigured Renovate token made it skip every workflow-file bump without a word. Nothing failed, the pull requests never appeared, and nobody noticed until we went looking for them.
CI: from the action to a tooling image
CI never depends on a developer's mise. The official action installs the pinned toolchain from .mise.toml, proven in the pilot repository:
- uses: jdx/mise-action@v5
with:
version: 2026.9.17 # pin mise itself
github_token: ${{ secrets.PUBLIC_GITHUB_TOKEN }}
On GitHub Enterprise, pass the github.com token explicitly. The action defaults to the workflow's own token, an enterprise token that fails against api.github.com just as it does on laptops.
The reusable Terraform workflows the modules call do not read .mise.toml yet. They install their own defaults, and only Terraform deliberately matches the repository pins. The team dropped a plan to have CI read the Terraform pin from each repository in favour of a tooling image a teammate had started in July. The image is built with mise from its own .mise.toml, so laptops and CI get tools the same way, and Renovate bumps the image's pins like any repository's.
The other reason is time. On one CD job we sampled, 70 of the 83 seconds went to installing tools. The objection in the working session was about value, not cost: an image saves little on a job that installs one tool. That holds, and the saving is in the Terraform test jobs that install six. Image size came up too, and our runners cache layers, so each runner pulls a given version once. The image's current release pins its Debian base by digest, and moving to that base cleared two high-severity vulnerabilities the scan kept flagging. Before a shared workflow adopts it, the image needs a digest reference, a Trivy scan and a cosign signature.
The workflows adopt it one or two at a time. Until a workflow runs the image, its repositories' Terraform bump, one pull request each, stays open on purpose, so local Terraform never runs ahead of CI.
The lockfile decision. mise can write a mise.lock recording each tool's resolved version, download URLs and checksums. We chose not to commit one in the module repositories. Their pins are already exact, so a lockfile would mainly add checksums. The price is a second file to keep in sync in thirty repositories, with the churn and merge conflicts that brings. The image is different. It builds from one repository, everyone's CI will run it, and it should resolve identically every time. Its .mise.toml sets lockfile = true.
Rollout rules
- Start with CI. Developers adopt a pinned toolchain once CI runs the same pins. Until then the local file is advice, and every Terraform bump waits.
- Remove the custom regex managers before upgrading Renovate. With both active, every pin gets two pull requests in every repository.
- Confirm the gate reports in every repository before switching automerge on. A required check that never runs does not fail. It waits, and nobody gets a failure to look at.
- Ship a template release that touches CI together with its workflow change. The child pipelines run the release before anyone reads the changelog.
Limits to watch
- One maintainer. Most of mise's commits come from its creator, and it ships several releases a week. Pin its version in CI and read the changelog before bumping.
- A young lockfile. It left experimental status in February 2026, and its format was still changing in September. We will revisit the module decision once it settles.
- Trust is code execution. Review a new
[hooks]or[env]block like a change to a CI script. For per-repository trust, mise's paranoid mode ties approval to the file's content. - Three-way drift. The image, a developer's global config and the repository file can each pin a different Terraform. The repository file always wins, so a baseline in every repository makes any central default decorative. Decide which layer owns which tool.
- Presence is not usage. Thirty files do not mean thirty developers using them. The token, trust and shell activation are each a point where someone gives up.
Results
The pilot started in May, and the rollout to the reusable modules closed in September. All 32 carry a .mise.toml with Terraform pinned to match CI, and TruffleHog and pre-commit kept current by Renovate. Thirty take the template's updates. The two generated from a personal clone of the template get them once their source is repointed, a one-line change. The first TruffleHog wave, from 3.90 to 3.97, merged across the fleet in a day. The root modules, the configurations that deploy infrastructure, come next with a template of their own, more than a hundred repositories of them.
The part we did not plan for is the one that matters most. The developers who tried it did not go back. A month in, one teammate wrote that he had put the right versions in mise and now just runs git commit and lets the hooks do their thing, and another called it the way to go for the whole squad in the session where we set our CI standards. Developers at a Fortune Global 500 company are excited about a version manager, which says how much the old way cost them.
What's next
The reusable modules were the easy half. They are libraries: one Terraform version each, no state, no deploy. The root modules, the configurations that deploy the infrastructure, are different. There are more than a hundred of them, 48 still carry a .terraform-version file, and each one's version has three readers: the developer's laptop, the deploy tool that plans and applies it, and the remote workspace that runs it. Pinning a root means making those three agree, and a Copier template for roots does not exist yet.
On the CI side, the reusable workflows move onto the tooling image one at a time, and each move releases a held Terraform bump. That is the second post, once the migration that gates it is done.
Frequently asked questions
Does mise replace tfenv and tgenv? Yes. mise reads the pins from .mise.toml and, for repositories still on asdf, from .tool-versions. Developers who keep tfenv lose nothing, because the file does nothing on a machine without mise.
Does Renovate support mise without custom rules? Yes. Renovate's native mise manager finds .mise.toml and opens the version bumps. On GitHub Enterprise it needs a github.com token in RENOVATE_GITHUB_COM_TOKEN for release notes and tool lookups.
Should a repository commit mise.lock? Where the pins are already exact, the lockfile mainly adds checksums and a second file to keep in sync. Commit it where identical resolution matters, such as the image every CI job runs.
Additional resources
- mise documentation, with the pages on GitHub tokens, trust and
mise.lock - Renovate's mise manager, Copier manager and automerge
- Copier and its
_skip_if_existssetting - jdx/mise-action for GitHub Actions
- aqua and direnv, the two routes we did not take
- Also on this blog, Kubernetes secret management at scale, a colleague's account of another change rolled out across a fleet of repositories
Written by

Sergio Fernandez
Senior DevOps Engineer
Sergio Fernandez is a Senior DevOps Engineer at Xebia, where he builds platform and identity infrastructure for large engineering organisations. He works on Terraform, CI/CD and the automation that keeps hundreds of repositories consistent without manual effort. Outside client work he maintains open-source tools and a homelab, and he prefers simple systems that make the correct behaviour obvious.
Our Ideas
Explore More Blogs
Contact













