Terramantle
Get Started Free
Terramate + Terramantle

Terramantle vs Terramate: one letter apart, and the CLI assumes you run both

Terramate splits one monolithic state into stacks and decides which ones run. That leaves every stack needing a backend, a lock, a scan and a registry to pull from. The terramantle CLI starts from a Terramate layout, scaffolds a mono or poly repo around it, and wires each stack to its own Terramantle workspace.

The sample repo I use to exercise the state scanner still has a .github.old/ directory in it. Four workflow files: plan.yml, apply.yml, terramate.yml and a first terramantle.yml. I wrote them by hand, for seven stacks, and they disagreed with each other about which OpenTofu version to install and which stacks counted as changed. The directory is still there because it is the reason terramantle init exists. It replaced the four files with one, and the one it wrote assumes Terramate.

That is the honest version of this page. People arrive here because the two names are one letter apart. The answer is not "pick one". It is that the Terramantle CLI treats a Terramate repo as the normal shape of an infrastructure repository, and this page shows what that looks like on disk.

What Terramate solves, and what it leaves on your desk

Terramate exists because one state file for everything does not survive contact with a second team. The fix is stacks: many small root modules, each with its own state, each plannable on its own. As soon as you have them you inherit three new problems. Which stacks did this commit touch, so CI does not plan all forty. In what order do they apply when the app stack reads an output of the network stack. And how do forty directories get the same backend block without forty copy-pastes.

Terramate answers all three. terramate list --changed diffs the stack tree against a base commit. after and before in a stack's own file give terramate run a dependency graph to walk. generate_hcl writes the shared files into every stack from one definition. Together they turn a monorepo of stacks into something a pipeline can reason about.

What it does not answer is where those forty states live, who may take the lock on each one, what is inside them once applied, and where the stacks' modules and providers come from. Terramate has no opinion on any of that, by design. That is the gap the CLI fills, and it fills it per stack rather than per repo, because that is the unit Terramate already gave you.

Why the CLI starts from a Terramate layout

Three things Terramate does well are the reason the scaffold is built around it rather than around a shell loop, and each one shows up later on this page as a file you can read.

  • Ordering is data, not a script. after, before, wants and tag filters live in each stack's own file, and terramate run walks the resulting graph. --reverse walks it backwards for a teardown and --dry-run prints the order without running anything, which is how I check a new after before it reaches CI.
  • Generation with real logic. generate_hcl is not a template engine pasting strings. Globals merge from the repo root down to the stack, with the more specific directory replacing the general one. tm_dynamic emits a block per element of a map. And evaluation is partial: global. and terramate. references resolve at generate time while var. and local. are copied through untouched, so generated files can still contain ordinary Terraform.
  • Change detection against git. terramate list --changed and terramate run --changed diff the stack tree against --git-change-base, so a pull request plans the stacks it touched and nothing else. A watch list widens that to files outside the stack, such as a shared local module.

Run terramantle init in a workspaces repo and Terramate is on unless you say --no-terramate. The discovery glob defaults to stacks/* because that is the Terramate convention, and the manifest comment says so. The plan it prints before touching anything:

$ terramantle init --structure mono --artefact workspaces --vcs github
#   · artefact 'workspaces' (from the directory layout)
#   + terramantle.hcl                    # the repo manifest (your source of truth)
#   + terramate.tm.hcl                   # stack orchestration + generated backends
#   + .github/workflows/terramantle.yml
#   + .github/CODEOWNERS
#   + .tflint.hcl
#   + stacks/example/{main.tf,stack.tm.hcl,versions.tf}
#   ~ .gitignore                         # terramantle ignore lines merged in

One stack is one Terramantle workspace is one independently versioned, scanned state. The scaffold does not write a backend into any stack. It writes the root terramate.tm.hcl and lets terramate generate emit _backend.tf beside each stack.tm.hcl, which means a stack you add next month gets its backend the same way the first one did. The skeleton stack is deliberately thin:

# stacks/example/stack.tm.hcl
stack {
  name        = "example"
  description = "Example stack scaffolded by terramantle."
}

# `_backend.tf` beside this file is generated by `terramate generate` from the
# root terramate.tm.hcl. Do not edit it; edit the generate_hcl block instead.

Mono repo: many stacks, one generate block

The root config the CLI writes carries two things. Globals that name the org and the backend host, and a generate_hcl block that lands in every stack. This is the file as the sample repo carries it, with the comments trimmed:

# terramate.tm.hcl  (managed by terramantle · re-rendered by `upgrade`)
terramate {
  config {
    git {
      default_branch = "main"   # change detection diffs against this
    }
  }
}

globals {
  tm_org       = "acme-demo"
  backend_host = "registry.terramantle.dev"

  # repo slug + stack path, lowercased and slugified:
  #   stacks/network  ->  state-sample-mono-repo-stacks-network
  workspace = tm_lower("state-sample-mono-repo-${tm_replace(terramate.stack.path.relative, "/[^a-zA-Z0-9]+/", "-")}")
}

generate_hcl "_backend.tf" {
  content {
    terraform {
      backend "http" {
        address        = "https://${global.backend_host}/state/${global.tm_org}/${global.workspace}"
        lock_address   = "https://${global.backend_host}/state/${global.tm_org}/${global.workspace}.lock"
        unlock_address = "https://${global.backend_host}/state/${global.tm_org}/${global.workspace}.lock"
        username       = "terramantle-ci"   # ignored; the token is the password
      }
    }
  }
}

Two details in there cost me time, so they are in the file rather than in a wiki. The workspace name folds in the repo slug and the stack's path, not just its basename. Two repos in one org can both have a network stack, and two stacks in one repo can share a basename under different directories, and neither silently overwrites the other's state. The slug comes from terramate.repo in terramantle.hcl, not from editing this file, because upgrade regenerates it.

The other is lock_address. It is not decoration. Without it OpenTofu never issues a LOCK, so concurrent applies do not exclude each other and Terramantle's state policy gate, which only runs on LOCK, never runs. Why Terraform sees 423 is what that gate looks like from the stack's side.

Adding a stack is then Terramate's own command, and the backend follows:

terramate create stacks/eu/network --tags network,eu
terramate generate          # writes stacks/eu/network/_backend.tf
git add stacks/eu/network   # commit the generated file; CI fails on drift

terramantle state publish later reads the workspace back out of that generated address, so however the expression names the workspace, the uploaded lock file and the state agree. It used to assume the directory basename. In the sample repo that meant the lock file went to network while the state sat in a prefixed workspace, and neither call errored.

Providers from the org registry, generated the same way

The backend is only half of what every stack needs from Terramantle. The other half is required_providers, and this is the part the CLI does not write for you. The skeleton's versions.tf pins required_version and nothing else, and the sample repo's stacks still point at registry.opentofu.org because they predate the provider registry. The same Terramate mechanism that wrote _backend.tf handles it, so I keep the block in a second root file. Terramate reads every .tm.hcl in the directory, and upgrade only rewrites files that carry its own managed header, so this one is yours and survives it.

# providers.tm.hcl  (yours; no "managed by terramantle" header, so upgrade leaves it)
globals {
  # Providers every stack may use. Keyed by local name; the org registry serves
  # them under <org>.registry.terramantle.dev/<namespace>/<type>.
  providers = {
    aws    = { namespace = "hashicorp", type = "aws",    version = "~> 5.0" }
    random = { namespace = "hashicorp", type = "random", version = "~> 3.6" }
  }
}

generate_hcl "_providers.tf" {
  content {
    terraform {
      required_version = ">= 1.7"

      tm_dynamic "required_providers" {
        attributes = {
          for name, p in global.providers : name => {
            source  = "${global.tm_org}.${global.backend_host}/${p.namespace}/${p.type}"
            version = p.version
          }
        }
      }
    }
  }
}

What lands beside each stack.tm.hcl after terramate generate:

# stacks/network/_providers.tf  (generated)
terraform {
  required_version = ">= 1.7"
  required_providers {
    aws = {
      source  = "acme-demo.registry.terramantle.dev/hashicorp/aws"
      version = "~> 5.0"
    }
    random = {
      source  = "acme-demo.registry.terramantle.dev/hashicorp/random"
      version = "~> 3.6"
    }
  }
}

The host is the org's subdomain rather than registry.terramantle.dev/acme-demo/... on purpose. Modules carry the org slug in the path, but OpenTofu resolves a provider source by host, and a user in several orgs would otherwise get whichever org the token resolved to. Service discovery on acme-demo.registry.terramantle.dev advertises /v1/providers/acme-demo/, so the client appends hashicorp/aws to an org-scoped route and membership is checked there. The same auth env --terraform call that sets TF_HTTP_PASSWORD exports a token for that host, with Terraform's own encoding of a hyphen as two underscores:

$ eval "$(terramantle auth env --terraform)"
$ env | grep -E '^TF_(HTTP|TOKEN)' | cut -d= -f1
TF_HTTP_PASSWORD
TF_TOKEN_registry_terramantle_dev               # modules, slug in the path
TF_TOKEN_acme__demo_registry_terramantle_dev    # providers, org in the host

The scaffolded workflow checks all three are set before it runs tofu init, because a missing TF_TOKEN does not error at the point it is missing. The provider download silently falls back to anonymous and dies much later with an opaque 401.

Globals are where this stops being a copy of versions.tf and starts earning its place. Terramate merges globals from the repo root down to each stack and the more specific directory wins, so a subtree can pin or extend the provider set without touching the root file. A labelled block sets one key path and leaves its siblings alone:

# stacks/eu/globals.tm.hcl  (applies to every stack under stacks/eu/)
globals "providers" "aws" {
  version = "~> 5.70"     # eu stacks pin tighter; stacks elsewhere keep "~> 5.0"
}

globals "providers" "cloudflare" {
  namespace = "cloudflare"
  type      = "cloudflare"
  version   = "~> 4.40"   # only the eu stacks get this entry
}

One caveat, stated because it is the kind of thing a page like this usually omits. Once a stack pulls hashicorp/aws from the org registry its .terraform.lock.hcl records the subdomain address, and the lock-file parser behind terramantle state publish only recognises registry.terraform.io and registry.opentofu.org hosts. An address on any other host is dropped with a parse error rather than failing the upload, so the upload succeeds, the provider is invisible to the at-risk gate, and --fail-on-atrisk cannot trip on it. That is a gap in Terramantle, not in Terramate, and the provider's own scan and serve rules still apply at download time.

Poly repo: one stack, the same contract

--structure poly is the same scaffold with the stack at the repo root. There is no discovery block, the skeleton's main.tf, stack.tm.hcl and versions.tf land beside the manifest, and the root terramate.tm.hcl still owns the backend. Nothing about the pipeline changes, which is the point: a team that keeps one repo per environment and a team that keeps forty stacks in one repo get the same workflow file, the same lock gate and the same publish step.

$ terramantle init --structure poly --artefact workspaces --yes
.
├── terramantle.hcl       # structure = "poly", no discovery block
├── terramate.tm.hcl      # same generate_hcl "_backend.tf" as the mono repo
├── stack.tm.hcl          # the repo IS the stack
├── main.tf
├── versions.tf
├── _backend.tf           # after `terramate generate`
└── .github/workflows/terramantle.yml

Switching later is a manifest edit. Change structure, move the files under stacks/, run terramantle upgrade --diff and read the plan before applying it.

Stack dependencies, and what the pipeline does with them

Terramate's ordering lives in the stack file. after and before take project-absolute paths, paths relative to the stack, or tag filters, and terramate create accepts them as flags so you never hand-write the block:

terramate create stacks/eu/app \
  --tags app,eu \
  --after "tag:network" \
  --after "/stacks/eu/data-platform"
# stacks/eu/app/stack.tm.hcl
stack {
  name        = "app"
  description = "app"
  id          = "6b1d…"
  tags        = ["app", "eu"]
  after = [
    "tag:network",             # every stack tagged network applies first
    "/stacks/eu/data-platform",
  ]
}

The scaffolded pipeline is built so that ordering is honoured where it matters and ignored where it would only slow you down. The plan job is a GitHub matrix, five stacks at a time, each saving its own plan artefact. Plans are independent reads, so the graph is irrelevant there. The apply job is different. It restores every saved plan into its stack directory, checks each one was built from the merge commit, and then hands control to Terramate. The template says why in its own comment:

# `terramate run` honours each stack's before/after ordering, which a
# parallel matrix cannot.
terramate run --changed --git-change-base "$BASE" -- tofu init -input=false -no-color
terramate run --changed --git-change-base "$BASE" -- tofu apply -input=false -lock-timeout=300s -no-color tfplan

So the network stack applies before the app stack that declared after on it, the app stack's lock request runs policy against the state the network stack just wrote, and a 423 on the app stack stops the walk rather than racing it. If you want parallel applies too, terramate run --parallel 5 keeps the order and the scaffold does not stop you editing the managed file, but upgrade will show you the diff next time.

One trap worth stating plainly. after and before control order only. They do not mark the app stack as changed when the network stack changes, so a commit that touches only stacks/eu/network plans and applies only that stack. If the app genuinely needs to re-plan when its upstream moves, say so with wants or a watch list. The scaffold will not guess at that for you, because getting it wrong in either direction is a production incident.

# stacks/eu/app/stack.tm.hcl  (the two ways to widen "changed")
stack {
  name  = "app"
  after = ["tag:network"]

  # Run the network stack whenever this one runs. wanted_by is the same edge
  # declared from the other side.
  wants = ["/stacks/eu/network"]

  # Mark THIS stack changed when a file outside it changes. Paths, not variables.
  watch = ["/modules/service", "../shared/policy.json"]
}

Two commands make the graph visible before CI does. terramate list --changed --git-change-base origin/main prints the stacks a branch would plan, and terramate run --changed --dry-run -- tofu plan prints the order it would run them in without running anything. --reverse walks the same graph backwards, which is the only sane way to destroy an app stack before the network it depends on.

What each stack gets from Terramantle

Once the backend lands, every stack in the graph gets the same four things without any further configuration in the repo.

  • A workspace of its own. Versioned state, server-side locking, and the ability to promote or roll back one stack's state without touching its neighbours.
  • Policy at the lock. The plan step takes the lock on purpose, so a policy refusal shows up in the pull request as a 423, not after merge.
  • A scan of what landed. Each new state serial is scanned asynchronously for secrets, misconfiguration and reachable endpoints, per stack, so a finding names the directory that caused it.
  • A registry to consume from. The same auth env --terraform call that authenticates the backend exports the TF_TOKEN variables for the org's module and provider registry, and the final job uploads every stack's lock file:
terramantle state publish --ci --fail-on-atrisk   # exit 3 if any pinned provider is at-risk

Keeping both honest in CI

Two generators means two ways to drift. The pipeline checks both before it plans anything, and the CLI gives you the same checks locally:

terramate generate --detailed-exit-code   # 2 = a committed _backend.tf is stale
terramate fmt --detailed-exit-code        # 2 = something needed reformatting
terramantle upgrade --check               # 3 = the scaffold has drifted from terramantle.hcl
terramantle doctor
#   [ok  ] scaffold               up to date with terramantle.hcl
#   [ok  ] terramate generate     generated code is up to date
#   [FAIL] lock files             1 workspace(s) missing .terraform.lock.hcl (stacks/data)
#   [ok  ] vcs trust              repo:acme/infra is trusted

doctor is read-only and exits 3 on any failure, so it drops into a pre-commit hook. The sample repo's Makefile runs the same gates as its CI, which is how I found out that terramate fmt has no --check flag.

What this does not do

Terramantle does not orchestrate, order or run your stacks, and it does not detect drift. Terramate does not host modules, providers or state, and has no view of what a state file contains. The CLI does not write after, before or wants for you, does not generate required_providers, does not generate lock files, and does not scaffold a pipeline for anything other than GitHub Actions and GitLab CI. Its README calls it an experiment, and everything it does can be done with curl and terramate directly. The sample repo at state-sample-mono-repo is the finished shape, seven LocalStack stacks that run without a cloud account, and it is where I test every claim on this page before I make it.

Sorting out the confusion

Is Terramantle the same thing as Terramate?

No. They're one letter apart and do different jobs. Terramate orchestrates your stacks: ordering, change detection, code generation, drift. Terramantle is the registry and state backend those stacks talk to. The Terramantle CLI scaffolds a repo that uses both, so the two names turn up in the same workflow file on purpose.

Do they compete?

No. Terramate decides which stacks run and in what order. Terramantle is where each of those stacks stores its state, takes its lock, and downloads its modules and providers from. Neither does the other job, and the scaffolded pipeline needs both to get through a single run.

Do I have to use Terramate to use Terramantle?

No. terramantle init --no-terramate writes a plain backend.tf into each stack instead of a terramate.tm.hcl, and the pipeline loses change detection and ordered apply. Terramate is the default for workspaces repos because a stack-per-state layout without an orchestrator is forty directories and a shell loop.

Does the scaffold need Terramate Cloud?

No. The generated pipeline installs the open-source Terramate CLI with terramate-action and a pinned version, and nothing in it calls Terramate Cloud. If you use Cloud for drift or a dashboard, that sits beside the scaffold rather than inside it.

Does the CLI write my stack dependencies for me?

No. The skeleton stack declares a name and a description and nothing else. after, before, wants and tags are yours to add, and terramate create writes them from flags. What the scaffold does promise is that the apply job runs through terramate run, so whatever ordering you declare is honoured on the default branch.

Can Terramate generate my required_providers block as well as the backend?

Yes, and the page shows the file. The CLI does not write it: the skeleton versions.tf pins only required_version, so a providers.tm.hcl beside the managed terramate.tm.hcl is yours, and upgrade leaves unmarked files alone. One caveat is stated below: a provider pulled through your org's registry subdomain is not yet recognised by the at-risk check in state publish.

Does Terramantle do orchestration or drift detection?

No. It doesn't run OpenTofu, order stacks or detect drift. It hosts modules, providers and state, runs policy when a stack asks for its lock, and scans what lands. The orchestration half of the scaffold is Terramate, and the CLI README calls the CLI itself an experiment.

Last reviewed

Terramantle is a private Terraform and OpenTofu registry. See pricing or read the FAQ.