Terramate

A Terramate repo, where each stack is one root.

Works

• Stacks apply in waves ordered by their after and before
• Only the stacks a change reaches, and those ordered after them, are planned
• Stale generated code fails the check

Differs

• Terramate Cloud and Terramate scripts are not read, and neither are watch files or wants and wanted_by.
• A drift pull request, rollouts and generate are refused, since their edits would land in code terramate generate owns.

On Terraform, choudoufu, GitLab

On Terraform

• Two overlapping pushes to one root can fail the newer apply with "Saved plan is stale"; run it again and it plans again.

On choudoufu

• terragucci does not read a root's required_version as a choudoufu release.

On GitLab

• Comment commands answer on a schedule, since a merge request note starts no pipeline.
• Roots lock on /terragucci apply or /terragucci lock, not at the first plan.
• The agent comment and drift fixes are GitHub and Forgejo only.

First step

Use Terramate

Proof

Terramate, on Forgejo

• Plan and review2provenPlan and review, Terramate2 checks, all proven.
  • a pull request that changes one Terramate stack plans that stack and the stacks whose after or before put them after it, and no other
  • the check job of a Terramate repo fails on stale generated code, naming the file terramate generate would change
• Approve and apply2provenApprove and apply, Terramate2 checks, all proven.
  • init takes the stacks of a Terramate repo as roots and cuts a wave per layer of their order: a stack after a tag or before another applies in the wave its order gives it, behind its own gate
  • a Terramate stack whose input block reads an output of an unapplied stack is held back, never planned on the mock, and applies on the output of the upstream once it has applied
• Locks and safety1provenLocks and safety, Terramate1 check, proven.
  • with apply.when: pull-request in a Terramate repo, a pull request applied on a comment locks the stack it changes, and a second pull request that changes that stack is refused with the stack and the holder named, its state left as the first applied it
• PolicynonePolicy, TerramateNo check recorded.
• DriftnoneDrift, TerramateNo check recorded.The drift pull request is refused: a live value belongs in the stack .tm.hcl or its own Terraform.
• Chat and notifynoneChat and notify, TerramateNo check recorded.
• Reports and visibilitynoneReports and visibility, TerramateNo check recorded.
• ModulesnoneModules, TerramateNo check recorded.Rollouts are refused: the pin is usually in code terramate generate writes.
• State and migrationnoneState and migration, TerramateNo check recorded.
• Agents and pull request environmentsnoneAgents and pull request environments, TerramateNo check recorded.
• Setup and runtimenoneSetup and runtime, TerramateNo check recorded.

• proven passes, and fails with the feature cut out
• not supported not supported by design; a corner mark means part of the area
• none no check recorded

Every check runs on OpenTofu on Forgejo. Runs on Terraform, choudoufu and github.com are expensive, so they re-run only the checks where the binary or forge changes what happens.

Open a cell for the checks behind it. Recorded: example checks, last full run Oct 8, 2026; per-forge checks Oct 7 to Oct 9, 2026; github.com Oct 10, 2026.

You can count on

• A plan note on every pull request
• Gated applies of the plans you approved
• No overlapping or stale applies
• Re-plan from a comment
• Scheduled drift checks
• OIDC roles, one to plan, one to apply
• Policy on every plan
• An audit trail in your bucket
• Secrets kept out of notes and logs
• Your state backend, as is
• Your own runners
• Your forge's sign-in and permissions

Then read

Tasks

Use Terramate

Background

Waves and approvals

Details

terragucci.yml keys