terramate: change detection built on Git, not on state

The free half is the engine, the paid half is the observation

The split is stated early and it is not subtle.

Terramate is a command line tool, an open-source orchestration and code generation engine, so that infrastructure as code written with Terraform, OpenTofu, Terragrunt or Kubernetes can scale. It can optionally be paired with a managed service, which is described as a hosted product that adds features for managing and observing the infrastructure you already manage with these tools, across one repository or several.

The numbered list of what you can do makes the division concrete. Four of the five items are things the command line tool does: splitting large state files into smaller stacks, generating backend and provider configuration, orchestrating commands across a dependency graph while deploying only what changed, and turning pull requests into deployments through your existing continuous integration. The fifth item is entirely the hosted product: observability, drift detection, asset management, misconfiguration detection, incident management, developer self-service and chat notifications.

The feature list repeats the same line further down. Multiple environments, dependencies, orchestration, change detection, code generation and automation blueprints read as tooling. Drift management, insights, misconfiguration detection with a large policy catalogue, asset inventory and audit trail read as the hosted side.

So the architecture is a local engine with an optional observer, and the boundary is deliberate.

If it never reads your state, it decides what changed by reading Git

This is the load-bearing claim in the document, and it is framed as a security property.

The readme says the tool does not require access to your state backend, your code or your cloud accounts, which is what makes it safe to use in any environment. That is repeated in the benefits list, where it is the basis of the security claim rather than an implementation detail.

Now follow the consequence. Change detection is built on top of Git. The tool deploys only the stacks that contain changes, and it follows changes into referenced modules and into Terragrunt dependencies rather than only into files in the stack itself.

So the definition of changed is a diff. That has two consequences worth stating. It works without credentials and without a plan, which is why onboarding is described as a single command with no refactoring. And it cannot detect that reality and the repository have diverged, because it never looks at reality. Drift is exactly that gap, and the readme places drift detection on the hosted side, alongside scheduled workflows and post-deployment detection.

For anyone reasoning about their own deployment: a manual change made in the cloud console is invisible to this tool, and the free tier will not tell you.

The argument for stacks is blast radius, not organisation

The first item in the numbered list is the one to read twice, because it names a failure mode rather than a feature.

Breaking up large, monolithic state files into multiple smaller stacks limits blast radius. It also reduces runtimes, and the readme adds that it unlocks better collaboration. Three consequences from one change, and the first is the real argument: a stack is the unit that can fail independently, so the unit of deployment is also the unit of risk.

The mechanism is a graph. Orchestration runs any command in any stack, with unlimited concurrency, and dependencies between environments are managed with output sharing and graph-based orchestration. So a stack can declare that it needs an output another stack produced, and the graph decides what has to run first.

The third item makes the change detection explicit: orchestrate commands such as the apply command in stacks, and deploy only stacks that contain changes.

The flexibility claim then matters in a specific way. Stacks can be arranged with workspaces, with directories, with Terragrunt, with variable files, with partial backend configuration, or any mix. That is what makes it usable on an existing repository rather than one written for it, and it is also why the tool is described as adopting a feature at a time rather than all at once.

Code generation is a compiler, and the repository runs on it

The second numbered item is generation, and the readme describes it in terms of duplication.

You can programmatically generate native backend and provider configuration, or any other arbitrary file, using what the readme calls the Terramate compiler. The feature list names the output formats: HCL, JSON and YAML, and the stated purpose is to keep your stacks free of repetition.

Two details make this more than template substitution. First, it generates the native configuration the underlying tool expects, rather than a wrapper of its own, which is what keeps the claim of no new syntax credible. Second, the repository itself is laid out as a set of stacks: the tree carries configuration files with a project-specific extension at the root, and one of them generates the linter's own configuration file. A repository that configures its own linter through its own generator is dogfooding the feature rather than describing it.

The other dogfooding is visible in the pipeline files. The tree has a file for one CI provider, another for a different one, and a directory of workflow definitions, sitting in a project whose feature list sells pre-configured workflows for exactly those providers.

Together those two things are the strongest evidence in the repository that the generation engine is the product, and the orchestration is one consumer of it.

It installs and runs the other tool for you

The dependency list tells you something the readme does not, which is how much of the work happens outside the process.

Three dependencies together describe installing and running an external binary: a wrapper around safe process execution, a version-aware installer for tools, and a library for fetching binaries. So the command line tool is willing to download the infrastructure tool it drives and to run it, which is a materially different security posture from a tool that shells out to whatever is already on your path.

Two more entries describe the interactive surface. One dependency is a declarative command line parser, and two others are shell completion libraries, which is the arrangement for a command with many subcommands. A set of four libraries from the same author provide a terminal user interface framework, so the tool can render prompts, lists and styled output rather than only printing lines.

And one entry is easy to miss: a small library whose purpose is checking whether a newer version has been published.

brew install terramate

That is an update check, which is worth knowing about in a tool whose selling point is not touching your infrastructure.

So the shape is: a parser, a terminal interface, an installer, a safe executor, and Git access. The last of those is the one the next section is about.

Terramate depends on Terragrunt, which answers the comparison question

The most-asked question about a tool like this is how it relates to the tool it sits on top of, and this repository answers it without ever framing it as a comparison.

The Go module requires a pinned release of the Terragrunt project as a direct dependency. Not an optional integration: a library dependency in the module file.

At the same time, the readme names Terragrunt three times as something Terramate works alongside. It is listed among the infrastructure tools whose scale Terramate supports. It has its own onboarding guide for an existing project. And the change detection description says it follows changes into Terragrunt dependencies, as well as into referenced modules for the two other tools.

Read together, the relationship is not competing alternatives: one is a dependency of the other, and the other has a dedicated onboarding path.

That also explains why the feature list mentions variable files and partial backend configuration as alternative ways to arrange stacks. Those are the arrangements the tool it depends on already established, and Terramate is deliberately able to live inside them instead of asking you to replace them.

The comparison questions in the readme's own link list go to documentation and to pricing pages rather than to a page arguing against anything, which is consistent with a project whose pitch is that it needs no migration.

The root Makefile is a ten-line dispatcher for three platform files

The build file is worth a short section because it explains the shape of the whole repository.

The root file declares a default goal of help, then chooses between two included files depending on whether the environment variable says the machine is Windows, and includes a third file either way. That is the entire file. Every rule lives in the makefiles directory.

The directory listing is the interesting part. There are around forty directories, and they are named after the concerns a tool of this kind has: the engine, the dependency injection wiring, the HCL evaluation layer, code generation, the Git integration, change detection, the printer, vendoring, the command surface, the binary entry points, event handling, error types, an interactive shell-like component, an expression evaluator over maps, and a module vendoring component.

Two of those deserve a note. There is a directory for the hosted client and another for its synchronisation, which is how the open repository carries the code that talks to the commercial service. And there is a directory for containers, next to the pipeline definitions and a continuous integration directory, so the tool's own automation is built from the pieces it sells.

There are also small fossils: a mock Terraform file and a log level test sitting at the repository root rather than inside a package directory, which is what happens when tests grow next to the thing they test.

A release candidate six days before the final, and a version file

Three releases are visible and the spacing tells you the cadence.

Version 0.17.2 was tagged at the end of July 2026, a release candidate for 0.17.3 in the first days of September, and the final 0.17.3 at the end of the same week as the last recorded push, which is dated 2026-09-08.

So a release candidate sits about six days ahead of its final, and the project is still below 1.0 after years of use. For a tool you pin in continuous integration, that means the version moves often and the release notes are where the behaviour changes are recorded.

The repository carries a version file at its root, alongside a change log, a security policy, a code of conduct, a third party notice file and an agent instruction file. The third party notice is the one that pairs with the licence: the project is under the Mozilla Public License, which is file-level copyleft, so vendored and generated code has to be attributed and the notice file is how that is discharged.

Everything else at the root is conventional for a Go project of this size, including an editor configuration file, a git attributes file and a markdown lint configuration.

The result is a repository that reads as a mature tool with an active release train, which is consistent with the README's claim that the paid tier is about enterprise features and support rather than about the engine itself.

Editorial conclusion

Terramate fits a team with one large infrastructure repository that has outgrown being a single state file, and that wants generated configuration instead of copy and paste. Two things to weigh before adopting it. The no-access property is a real constraint on what it can tell you: because change detection reads Git, it knows what you changed and cannot know what someone applied out of band, so drift detection is where the readme places that problem, and drift detection is behind the paid product. And the tool is pre-1.0 with release candidates six days ahead of finals. Nothing here argues against it for the job it describes. It does mean the free part is the orchestration and generation layer, and the observation layer is the commercial one.

Frequently asked questions

Official sources

1. License: MPL-2.0
2. Project website
3. README
4. Releases
5. terramate-io/terramate on GitHub