# terragucci

> The whole Terraform lifecycle, handled: grouped plans on every pull request, applies in gated waves, drift reports, module publishing and rollouts, for Terraform, OpenTofu, choudoufu, Terragrunt, Atmos, Terramate and CDK Terrain on GitHub, GitLab or Forgejo.

Every page is true as written: a command or key on this site works as the page says. A key that `terragucci config check` refuses is not part of terragucci. The validation page (https://intentius.io/terragucci/reference/validation/) lists the checks every generated pipeline passes.

terragucci is built on chant (https://intentius.io/chant/), which keeps the approvals and records on `chant/lifecycle`. SQL Yodeler (https://intentius.io/sql-yodeler/) manages ClickHouse and Postgres schemas on the same approvals.

Agents adopting terragucci in a repository: start with https://intentius.io/terragucci/getting-started/agents/.

A page with a prompt carries it under "Optional: hand this page to your coding agent", and llms.txt lists it under the page. Every prompt forbids apply, approve and merge; those stay with the person.

---

# Set up with a coding agent

Source: https://intentius.io/terragucci/getting-started/agents/

## Optional: hand this page to your coding agent

```text
Set up terragucci in this repository.
Read https://intentius.io/terragucci/llms.txt first, then
https://intentius.io/terragucci/getting-started/agents/ and follow it.
Open a pull request with the result.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

Setup needs no agent. [Get your first plan note](/terragucci/getting-started/) gives every step by hand, and only four opt-in features [run a model](/terragucci/#opt-in-coding-agent).

Give the prompt above to an agent working in a repository of Terraform or OpenTofu roots, including a Terragrunt, Atmos, Terramate or CDK Terrain repo.

## Agent inputs

| File | Holds |
|---|---|
| [`llms.txt`](https://intentius.io/terragucci/llms.txt) | every page, with a one-line description |
| [`llms-full.txt`](https://intentius.io/terragucci/llms-full.txt) | the text of every page in one file |
| Copy page as Markdown, under each page's title | that page's text, with its prompt |

A task page's own prompt sits under its title as "Optional: hand this page to your coding agent". Each one carries the line in step 5.

A key that `terragucci config check` refuses is not part of terragucci.

## Steps for the agent

1. Install terragucci with `npm i -D @intentius/terragucci` and run `npx terragucci init --dry-run --json`. Show the user the findings with their reasons and the files it would write.
2. Check what it found. Pass `--binary` or `--forge` if either is wrong, or ask the user.
3. Write a `terragucci.yml`, as small as possible, only if the defaults are wrong; [terragucci.yml keys](/terragucci/reference/config/) lists every key.
4. Run `npx terragucci init` to write the pipeline, and show the user the file it wrote.
5. Open a pull request with the config and the files `init` wrote; check `git status` so the commit holds nothing else. Then stop. Approvals are records on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle), and they belong to the user.

   ```text
   Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
   ```
6. Under `approval: sealed`, tell the user to add their key to `.chant/allowed_signers` ([Before your first approval](/terragucci/getting-started/#first-approval)). Do not add a key yourself. The file must be on the default branch before the first merge that destroys something, because the apply reads it from before the merge.

## Rules for the agent

- Set terragucci up or change its config from the shell with `--json`, and parse the envelope ([JSON output](/terragucci/reference/cli-json/)).
- Read what terragucci already wrote through `terragucci mcp`, when the user has added it ([Read the estate over MCP](/terragucci/guides/agent-read-over-mcp/)).
- Run `npx terragucci config check --json` after writing a config; it lists every problem at once.
- Approvals belong to people. Print the `terragucci approve` command for a waiting wave but never run it; an approval made over MCP or ACP is refused.
- [Responses to pipeline events](/terragucci/reference/responses/) need no model.
- Credentials stay in the forge's secrets. The config names environment variables (`token_env`) and never holds a value.

## MCP or `--json`

| You want to | Use | Why |
|---|---|---|
| find the roots, binary and forge, write a config, check it, write the pipeline | the CLI with `--json` | these commands write files in the repo, and the envelope gives each finding and the exit code |
| plan a root, or run a response in dry run | the CLI with `--json` | they run the binary in the checkout |
| read the estate, a root's last apply, a run's report, the state versions, the audit trail or the DORA figures | `terragucci mcp` | it reads the reports bucket with the credentials in its own environment, and every tool only reads |
| find a waiting wave and its digest | `terragucci mcp`'s `waiting` tool | it prints the `terragucci approve` command for a person to run |
| approve, apply, override or merge | neither | these belong to a person at a shell; the server has no such tool, and an approval made over MCP is refused |

## Next

After setup, see [read the estate over MCP](/terragucci/guides/agent-read-over-mcp/), [summarize a refused wave](/terragucci/guides/agent-refused-wave/) (comment-only token), [change a pull request](/terragucci/guides/agent-change-a-pull-request/), [fix drift](/terragucci/guides/agent-fix-drift/), and [review a pull request](/terragucci/guides/agent-review-a-pull-request/).

---

# terragucci

Source: https://intentius.io/terragucci/

With the [0.4.7 release](/terragucci/reference/whats-new/), every approval is one command, `terragucci approve`. 0.4.5 added SQL over the reports bucket, resuming a killed choudoufu wave from its records, and imports from HCP Terraform, Scalr, Spacelift and env zero. Watch the [launch party](/terragucci/launch-party/) from the Rome launch.

## Your forge and your bucket

terragucci reads your roots and runs your binary. Code, state backend and provider pins stay as you have them.

| Where it runs | What you set | Page |
|---|---|---|
| GitHub, GitLab or Forgejo CI | nothing: `init` reads the forge from the `origin` remote and writes its pipeline format | [Per forge](/terragucci/guides/add-to-a-repo/#per-forge) |
| S3, GCS or Azure Blob, for your state and the reports | `oidc` for keyless cloud identities, `reports.bucket` for the reports | [Credentials](/terragucci/reference/pipeline/#credentials), [Keep reports in a bucket](/terragucci/guides/keep-reports-in-a-bucket/) |

## See every run as a trace

Every plan, apply and drift run sends one OpenTelemetry trace and the pipeline's metrics over OTLP to your collector.

| The trace shows | Page |
|---|---|
| The stage, then a span per wave and per root, with digests, change counts and status | [Send traces and metrics](/terragucci/guides/send-traces-and-metrics/) |
| The binary's own spans inside each root: OpenTofu's resources, and with choudoufu its provider calls and state lock waits | [Traces and metrics](/terragucci/reference/observability/#spans-from-the-binary) |
| Metrics and the Grafana dashboards `init` writes with `dashboards: true` | [The metrics](/terragucci/reference/observability/#the-metrics) |

## The lifecycle around your roots

`init` writes the pipeline for these stages in your forge's own format. [Architecture](/terragucci/concepts/how-it-works/).

## Waves and approvals

A change goes out a few roots at a time, starting with the [canary](/terragucci/concepts/glossary/#canary) roots. By default a wave that destroys or replaces something waits for an approval, which covers exactly the plans it was shown.

The report lists each wave with the digest of its plans and links the approval record that let it go out. [Waves and approvals](/terragucci/concepts/waves-and-approvals/).

## One note for two hundred plans

Roots taking the same change share one diff that shows each value before and after. Every destroy is named. Each root's whole plan sits collapsed below, and [the full report](/terragucci/reference/report/) links each root's plan.

## Module publishing and pinned rollouts

| You get | Turn it on | Page |
|---|---|---|
| Each changed module released after the apply, as a git tag or an OCI artifact, and with attest signed with cosign | `modules.publish`, `modules.attest` | [Publish your modules](/terragucci/guides/publish-modules/) |
| A new version rolled out to every repo that pins the module, one pull request per wave | `terragucci rollout`, or `rollouts:` for a scheduled job | [Roll out a new module version](/terragucci/guides/roll-out-a-module-version/) |

## With choudoufu

choudoufu is the OpenTofu fork from the team behind terragucci. Set `binary: choudoufu` ([set it up](/terragucci/guides/use-a-binary/#choudoufu)) and the pipeline also gets:

| You get | Page |
|---|---|
| A live check in `tf-check` on every push, before the apply waves, with no cloud credentials | [Check](/terragucci/reference/stages/#check) |
| One record per resource in an S3 backend you own, each write conditional, with no lock table or database to run; the state file is a cache | [Record writes](/terragucci/concepts/locking-and-staleness/#record-writes) |
| How long a wave waited for a state lock, and how many tries it took | [State lock waits](/terragucci/reference/observability/#state-lock-waits) |
| Which provider calls were slow, and the resource each was for | [What the report lists](/terragucci/reference/observability/#report-contents) |
| Timings summed by resource type, so a large estate's report stays readable | [What the report lists](/terragucci/reference/observability/#report-contents) |
| Changes to different resources of one estate apply at the same time; an overlapping change waits, or is refused, before it reaches the cloud; a killed apply leaves nothing to release | [Locking with choudoufu](/terragucci/concepts/locking-and-staleness/#with-choudoufu) |
| A role scoped to one estate by an IAM condition on the `tofu-estate` tag, refused on another estate's resources | [Live resource markers](/terragucci/concepts/locking-and-staleness/#live-resource-markers) |

## Pull request automation

These are plain CI jobs in your pipeline.

| On a pull request | How you start it | Forges | Page |
|---|---|---|---|
| One grouped plan note and a `terragucci/plan` status | open or push to the pull request | all three | [Get your first plan note](/terragucci/getting-started/) |
| Tips and policy results on the plan | on by default with the plan; `tips: false` turns tips off, `policy` adds checks | all three | [Tips](/terragucci/reference/tips/), [Policy](/terragucci/reference/policy/) |
| A re-plan | comment `/terragucci plan [root]` | all three; GitLab through the comments schedule | [Re-plan from a comment](/terragucci/guides/re-plan-from-a-comment/) |
| Root locks by comment | comment `/terragucci lock` or `/terragucci unlock` | GitHub and Forgejo; GitLab with `apply.when: pull-request` and `comments:` set | [Locks](/terragucci/guides/apply-before-merge/#locks) |
| Root locks from the first plan | `locks: plan` | GitHub and Forgejo | [Locks](/terragucci/guides/apply-before-merge/#locks) |
| Apply before merge, then merge after the last wave | `apply.when: pull-request`, then comment `/terragucci apply [wave-<n>]` | GitHub, Forgejo, and GitLab with `comments:` set | [Apply before merge](/terragucci/guides/apply-before-merge/) |
| An approval for a waiting wave | `approval: ledger`, `pr-review` or `sealed`; run `terragucci approve` | all three | [Approve a waiting wave](/terragucci/guides/approve-a-wave/) |
| A recorded policy override | a listed person runs `terragucci override` | all three | [Override a policy denial](/terragucci/guides/approvals-runbook/#override-a-policy-denial) |
| Comment commands on GitLab | `comments:` sets the schedule that answers merge request notes | GitLab | [Re-plan from a comment](/terragucci/guides/re-plan-from-a-comment/) |

### Opt-in: coding agent

Only these four features run a model. Each is off until you set it up and needs a model API key in your forge's secrets.

| Feature | Turn it on | Forges | Page |
|---|---|---|---|
| Comment `/terragucci agent <ask>` and an agent commits the change to the pull request | `agent.comment` in `terragucci.yml` | GitHub and Forgejo | [Have an agent change a pull request](/terragucci/guides/agent-change-a-pull-request/) |
| When drift opens the drift issue, an agent changes the code to match what is live, in a pull request | `agent.drift` in `terragucci.yml` | GitHub and Forgejo | [Have an agent fix drift](/terragucci/guides/agent-fix-drift/) |
| A note on each pull request comparing its description with its plan: risk, mismatches, questions | `review.agent` in `terragucci.yml` | all three; GitLab through the comments schedule | [Have a model review a pull request](/terragucci/guides/agent-review-a-pull-request/) |
| A summary of what moved in a refused wave | add the explain-refusal job under `own_jobs` | all three | [Have an agent summarize a refused wave](/terragucci/guides/agent-refused-wave/) |

A coding agent at your desk reads the estate (down to a root's last apply), the audit trail and the DORA figures through `terragucci mcp`, a read-only MCP server that runs no model ([Read the estate over MCP](/terragucci/guides/agent-read-over-mcp/)).

## Security

| Guard | What it means |
|---|---|
| Plan and apply use separate roles | `oidc` takes one identity for plan and one for apply, and terragucci rejects the same role for both |
| The plan job cannot apply | it runs the pull request's code with the read-only plan role and never gets the apply role; under `approval: sealed` an approval also needs a signer's key, which no job holds |
| A changed plan is refused | a gated wave whose plans moved after the approval applies nothing and names both digests |

[The threat model](/terragucci/reference/threat-model/) lists what each job can reach on each forge.

## Limits

What terragucci leaves to your forge and your cloud, and what it does not support.

Recorded checks show what is proven on each tool and forge ([validation](/terragucci/reference/validation/)). Apache-2.0.

## Hand the setup to your agent

[Add terragucci to a repo](/terragucci/guides/add-to-a-repo/) has the same steps by hand. Or paste this into Claude Code, Codex or Cursor in your repository. [The agent page](/terragucci/getting-started/agents/) says what the agent does. It never applies and never approves.

Then the [guides](/terragucci/guides/add-to-a-repo/) cover tasks and the [reference](/terragucci/reference/config/) the details; the [concepts](/terragucci/concepts/how-it-works/) and the [glossary](/terragucci/concepts/glossary/) explain the reasons and the terms. terragucci is built on [chant](https://intentius.io/chant/), and [SQL Yodeler](https://intentius.io/sql-yodeler/) brings ClickHouse and Postgres schemas through the same approvals.

---

# Architecture

Source: https://intentius.io/terragucci/concepts/how-it-works/

`npx terragucci init` writes a pipeline file for your forge; its CI runs everything in terragucci's image. It needs no server or hosted service and keeps state in your backend. The package is Apache-2.0.

## A change, start to finish

Each step names its stage and the identity it runs with. All of them run on GitHub, GitLab and Forgejo.

1. The pull request: `tf-check` and `tf-plan`, with the read-only plan identity. `tf-check` formats and validates every root on the branch push (on a pull request only from a fork). `tf-plan` plans only the roots the change reaches, one [layer](/terragucci/concepts/glossary/#layer) at a time.

2. The plan note: `tf-plan` posts one grouped comment naming every destroy and replacement, and sets `terragucci/plan`. `/terragucci plan` re-plans from a comment; on GitLab it needs the [`comments`](/terragucci/reference/config/#keys) schedule.

3. The merge: any push to the default branch runs `tf-apply` with the apply identity, one push at a time. Under the default `on-destructive` gate only a wave that destroys or replaces waits. With [`apply.when: pull-request`](/terragucci/reference/config/#apply-before-merge), a writer's `/terragucci apply` comment applies the open head instead (on GitLab, with the `comments` schedule). The [guide](/terragucci/guides/apply-before-merge/) lists what it refuses.

4. The waves: `tf-apply` runs one job per [wave](/terragucci/concepts/glossary/#wave), `waves.canary` roots first, then dependency order. With [`waves.jobs`](/terragucci/concepts/waves-and-approvals/), a large wave gets a job that decides it and share jobs that apply it. Each wave plans after the previous one applied.

5. The approval: no stage runs. A waiting job exits 3 and prints the approve command for its [set digest](/terragucci/concepts/glossary/#set-digest). A person runs `terragucci approve` to record an approval on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle), using their push access to that branch; under `approval: pr-review` a review of the head also counts. With `approval: sealed` the approval also carries a seal that must verify against `.chant/allowed_signers` from the commit before the applied one.

6. The apply: `tf-apply`, with the apply identity. `terragucci approve` or a rerun of the job restarts the waiting wave. So does a push or a `/terragucci apply` comment (on GitLab, with the `comments` schedule). The wave re-plans and refuses on a changed digest, and never applies a root twice. A comment that fails a [check](/terragucci/reference/pipeline/#ignored-comments) runs nothing.

7. Drift: with `drift:` set to a schedule, `tf-drift` plans every root with `-refresh-only` under the plan identity and keeps one issue updated, closing it when drift is gone. It never applies.

## Components

| Where | What |
|---|---|
| your machine | `npx terragucci init`, once and after a config change; `terragucci approve`, to approve a wave |
| your forge's CI | every stage: check and plan on pull requests, apply on the default branch or the pull request, drift on schedule, comment jobs |
| your repository | the pipeline file, an optional `terragucci.yml`, the `chant/lifecycle` branch, and under `approval: sealed` [`chant.workspace.json`](/terragucci/concepts/glossary/#chantworkspacejson) and the signers file |
| your cloud | your state (with [choudoufu](/terragucci/concepts/glossary/#choudoufu), a tag on each resource in its place), and the plan and apply identities the jobs assume over OIDC |
| your bucket, if you set one | the reports and their index, the resource inventory and change history, and with `terragucci estate` and `terragucci audit` the delivery metrics and the audit trail ([the layout](/terragucci/reference/reports-bucket/)) |

The plan identity is read-only because pull request code runs with it. Applying before merge gives the apply identity to unmerged code, so it is opt-in.

## Next

- [Get your first plan note](/terragucci/getting-started/) sets it up on a repository.
- [The tutorial](/terragucci/tutorial/) runs each step on a 15-root example on your laptop.
- [Waves and approvals](/terragucci/concepts/waves-and-approvals/) explains the waves and the gate.
- [The approvals runbook](/terragucci/guides/approvals-runbook/) has the commands for signers, pending waves and refusals.
- [The glossary](/terragucci/concepts/glossary/) defines terragucci's words and lists the ones that mean something else in Terraform.

---

# Get your first plan note

Source: https://intentius.io/terragucci/getting-started/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/getting-started/ and https://intentius.io/terragucci/getting-started/agents/.
Set up terragucci in this repository.
Run `npx terragucci init --dry-run --json` and show me the findings before writing anything.
Then run `npx terragucci init` and open a pull request with the files it wrote, package.json and package-lock.json only.
Do not create secrets.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

CI does this: everything runs as jobs in your CI and lands in your git and your bucket. No account, no sign-in, no platform.

| You get | Where it is shown |
|---|---|
| No server to host | [What runs where](/terragucci/concepts/how-it-works/#components) |
| GitHub, GitLab or Forgejo | [Per forge](/terragucci/guides/add-to-a-repo/#per-forge) |
| Object storage on AWS, GCP or Azure, for state and reports | [Credentials](/terragucci/reference/pipeline/#credentials), [Keep reports in a bucket](/terragucci/guides/keep-reports-in-a-bucket/) |
| Tracing and metrics | [Send traces and metrics](/terragucci/guides/send-traces-and-metrics/) |
| Rich lifecycles | [Architecture](/terragucci/concepts/how-it-works/) |
| Gated waves | [Waves and approvals](/terragucci/concepts/waves-and-approvals/) |
| Aggregated plan output | [Plan grouping](/terragucci/concepts/why-plans-are-grouped/) |
| Module publishing and pinned rollouts | [Publish your modules](/terragucci/guides/publish-modules/), [roll out a version](/terragucci/guides/roll-out-a-module-version/) |

## Result

A pull request with one plan note that groups the roots a change reaches and names every destroy.

## Prerequisites

| You need | Why |
|---|---|
| a repo of Terraform or OpenTofu roots, or a Terragrunt, Atmos, Terramate or CDK Terrain repo, on GitHub, GitLab or Forgejo | terragucci reads the roots and the forge from the repo |
| Node.js 22 or later, on your machine only | `init` is an npm package; the pipeline runs in terragucci's CI image |
| a way for CI to read your state and providers | the plan job runs `plan`; see [Environment variables and credentials](/terragucci/reference/environment/) |
| push access to the repo | you commit the generated pipeline |

## Steps

1. Install terragucci from the root of the repo.

   ```bash
   npm i -D @intentius/terragucci
   ```

2. Preview what it finds. This writes nothing.

   ```bash
   npx terragucci init --dry-run
   ```

   ```text
   found 15 roots in 2 layers, tofu 1.13.1 (tofu on the path), forge github (the origin remote (github.com))
   would write .github/workflows/terragucci.yml
   no terragucci.yml needed (defaults fit)
   dry run: nothing was written
   ```

   | Found | Means | If wrong |
   |---|---|---|
   | [roots](/terragucci/concepts/glossary/#root) | directories with a backend, `cloud` block, [choudoufu](/terragucci/concepts/glossary/#choudoufu) `live` block or provider; in a Terragrunt repo, the units `terragrunt find` lists | `--json` says why |
   | layers | dependency order, the [waves](/terragucci/concepts/glossary/#wave) | |
   | [binary](/terragucci/guides/use-a-binary/) | `tofu` or `terraform` and its version; Terragrunt runs it underneath | `--binary` |
   | forge | the `origin` remote | `--forge` |

   If you have a `terragucci.yml`, run `npx terragucci config check` first. It names the approval mode and any unknown key, with the keys it accepts. The example's output:

3. Write the pipeline.

   ```bash
   npx terragucci init
   ```

**GitHub**

   ```text
   found 15 roots in 2 layers, tofu 1.13.1 (tofu on the path), forge github (the origin remote (github.com))
   wrote .github/workflows/terragucci.yml
   no terragucci.yml needed (defaults fit)
   ```

**GitLab**

   ```text
   found 15 roots in 2 layers, tofu 1.13.1 (tofu on the path), forge gitlab (the origin remote (gitlab.com))
   wrote .gitlab/terragucci.yml
   wrote .gitlab-ci.yml
   no terragucci.yml needed (defaults fit)
   ```

   The jobs go in `.gitlab/terragucci.yml`. A `.gitlab-ci.yml` you already have keeps its jobs and gains an `include:` of that file; [add terragucci to a repo](/terragucci/guides/add-to-a-repo/) has the cases.

**Forgejo**

   ```text
   found 15 roots in 2 layers, tofu 1.13.1 (tofu on the path), forge forgejo (the origin remote (codeberg.org))
   wrote .forgejo/workflows/terragucci.yml
   no terragucci.yml needed (defaults fit)
   ```

   The defaults need no `terragucci.yml`; [terragucci.yml keys](/terragucci/reference/config/) lists every key.

4. Give the pipeline a token.

**GitHub**

   The jobs use the run's `github.token`, so there is nothing to add.

**GitLab**

   Add `GITLAB_TOKEN` under Settings, CI/CD, Variables: a masked project access token with the `api` scope.

   | `terragucci.yml` | Plan job | Plan note | `GITLAB_TOKEN` |
   |---|---|---|---|
   | no `gitlab` key (the default) | holds the token, so a merge request's code can use it as the project's bot | posted by the plan job at once | a masked variable |
   | `gitlab: { token: protected }`, with `comments:` set | holds no token | posted by the comments schedule's job | a masked and protected variable, on a protected default branch |

**Forgejo**

   Each run brings its own token, so no secret is needed.

   Cloud roles over OIDC and the required status are in [Add terragucci to a repo](/terragucci/guides/add-to-a-repo/).

5. Commit and open a pull request.

   ```bash
   git switch -c add-terragucci
   git status
   git add -A
   git commit -m "Add terragucci"
   git push -u origin add-terragucci
   ```

   `git status` should list the pipeline files `init` wrote and the two package files. Put `node_modules` in `.gitignore`. Open the pull request, then change a line in one root, since a change that touches no root has nothing to plan.

6. Read the plan note. The plan job leaves one comment and a `terragucci/plan` status:

**GitHub**

   A pull request comment, with the status in the checks box.

**GitLab**

   A merge request note; the widget above it counts creates, updates and deletes.

**Forgejo**

   [The plan report](/terragucci/reference/report/) explains each part.

## First approval

With the default [gate](/terragucci/concepts/glossary/#gate), a wave waits for a person only when its plan destroys or replaces something. You approve it from your machine with [`terragucci approve`](/terragucci/reference/cli/#approve).

| Approval mode | Set up once |
|---|---|
| `ledger`, the default | nothing |
| `pr-review`, a pull request review counts | `approval: pr-review` in `terragucci.yml`; to hold unreviewed changes, require `terragucci/approval` on GitHub or Forgejo, or an approval rule on GitLab: [approve by review](/terragucci/guides/approve-a-wave/#approve-by-review-approval-pr-review) |
| `sealed`, signed approvals | the same, and your ssh public key in `.chant/allowed_signers` on the default branch before the first change that destroys something: [set up the signers file](/terragucci/guides/approve-a-wave/#set-up-the-signers-file) |

## Next

- [Approve a waiting wave](/terragucci/guides/approve-a-wave/) when a change destroys something.
- [Turn on drift checks](/terragucci/guides/turn-on-drift-checks/) to find changes made outside Terraform.
- [Govern many repos from one place](/terragucci/guides/govern-many-repos/) with a [control repo](/terragucci/concepts/control-repo/) once one repo works.
- [Threat model](/terragucci/reference/threat-model/) for what the jobs can reach and the branch protection they rely on.

---

# Boot the example

Source: https://intentius.io/terragucci/tutorial/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/tutorial/.
Clone https://github.com/INTENTIUS/terragucci, run `npm ci` and `just example up` as the page says, and report the Forgejo URL and the boot time. If it fails, match the error to "Troubleshooting" and tell me the fix.
`just example up` applies the example to floci, its local AWS stand-in. That is the one exception to the line below, and only against floci.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

You need no cloud account to run terragucci against a small shop's estate on your machine.

| Page | You see | Time |
|---|---|---|
| Boot the example (this page) | 15 roots applied by a local pipeline | about 10 min the first time |
| [Your first pull request](/terragucci/tutorial/first-pull-request/) | the check stage passing, then failing on formatting | 5 min |
| [One note for fifteen plans](/terragucci/tutorial/one-note/) | twelve plans grouped in one note | 5 min |
| [Waves and approvals](/terragucci/tutorial/waves/) | a change applied a wave at a time | 10 min |
| [A wave that changed](/terragucci/tutorial/changed-wave/) | an approved wave refusing to apply after one of its roots changed | 5 min |
| [Drift](/terragucci/tutorial/drift/) | a drift report naming the root | 5 min |
| [Publishing and pinning modules](/terragucci/tutorial/modules/) | a module version rolled out one pull request per wave | 10 min |
| [Tips](/terragucci/tutorial/tips/) | a tip on a floating provider version | 5 min |
| [See your runs](/terragucci/tutorial/see-your-runs/) | runs on terragucci's Grafana dashboards | 10 min |
| [The same shop on Terragrunt](/terragucci/tutorial/terragrunt/) | the estate as 15 Terragrunt units | 15 min |
| [Clean up, then your own repo](/terragucci/tutorial/your-repo/) | terragucci on a repository of your own | 10 min |

## Prerequisites

| You need | Why |
|---|---|
| Docker, with 4 GB of memory free | the forge, its runner and the AWS stand-in run as containers |
| [`just`](https://just.systems), `git` and `jq` | the commands below are `just` recipes |
| Node.js 22 or later | `just example up` runs `npx tsx` and builds terragucci from the clone |
| about ten minutes | the first boot pulls the images and builds the CI images |

Clone terragucci and install its dependencies.

```bash
git clone https://github.com/INTENTIUS/terragucci && cd terragucci
npm ci
```

## Boot it

```bash
just example up
```

It starts Forgejo (a local forge) with its runner, and floci (an AWS stand-in). Then it pushes the example and the pipeline applies every root:

The last line is the boot time. Later boots skip the image pulls and builds.

## Result

Open the Forgejo link, at `localhost:3300` unless you changed the port. The repo is the shop's whole estate:

| Path | What |
|---|---|
| `modules/service/` | one service: a bucket, a jobs queue, a records table |
| `envs/dev/platform` | each environment's logs bucket |
| `envs/dev/orders` | orders, payments, search and email, each calling `modules/service` |
| `envs/staging/...`, `envs/prod/...` | the same five roots each |
| `terragucci.yml` | the whole terragucci config |

Three environments of five roots make fifteen. A change to `modules/service` reaches twelve roots. Prod payments differs because its jobs queue has a dead-letter queue.

The platform roots hold the logs bucket, so terragucci applies them before the services.

The pipeline run shows every root applied:

`terragucci.yml` is four lines. Dev is the canary wave, and drift is checked every morning at six:

```yaml
binary: tofu
waves:
  canary: ["envs/dev/*"]
drift: "0 6 * * *"
```

With Terraform, `binary: terraform` runs the same pipeline ([Choose your binary](/terragucci/guides/use-a-binary/)). Terragrunt users get the same shop as units on [its own page](/terragucci/tutorial/terragrunt/).

## Troubleshooting

| You see | Try |
|---|---|
| `port is already allocated` | port 3300 or 4580 is taken. Set `TERRAGUCCI_FORGEJO_PORT` or `TERRAGUCCI_FLOCI_PORT` to a free one and run `just example up` again. |
| the pipeline waits and never starts | the runner has not registered. `docker logs terragucci-forgejo-runner` shows why; `just example up` re-registers it. |
| containers restart or Docker stops answering | Docker is short of memory. Give it 4 GB. |
| a link to `http://forgejo:3000/...` does not open | that is Forgejo's address inside the stack. On your laptop the page is at `http://localhost:3300/...`: change the start of the link. |

## Reset and restart

`just example reset` closes every pull request and puts the estate back the way it booted. `just example down` removes everything, and `just example up` brings it back from nothing.

Go on to [your first pull request](/terragucci/tutorial/first-pull-request/).

---

# Add terragucci to a repo

Source: https://intentius.io/terragucci/guides/add-to-a-repo/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/add-to-a-repo/ and https://intentius.io/terragucci/getting-started/agents/.
Set up terragucci in this repository for its forge.
Run `npx terragucci init --dry-run --json` and show me the findings before writing anything.
Then run `npx terragucci init` and open a pull request with the files it wrote, package.json and package-lock.json only.
List the token, OIDC roles and required status I must set in the forge settings.
Do not create secrets, variables or branch protection yourself.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

A plan note and a `terragucci/plan` status on every pull request or merge request, and one apply job per wave on the default branch (with [`waves.jobs`](/terragucci/concepts/waves-and-approvals/#a-wide-wave-across-jobs), a deciding job and its share jobs). Everything runs as jobs in your own CI and lands in your git and your bucket; there is no account to create. Pick your forge in any tab and the other forge tabs on the site follow.

## Per forge

| | GitHub | GitLab | Forgejo |
|---|---|---|---|
| Pipeline file | `.github/workflows/terragucci.yml` | `.gitlab/terragucci.yml`, included from `.gitlab-ci.yml` | `.forgejo/workflows/terragucci.yml` |
| Hosts `init` knows | github.com | gitlab.com, `gitlab.*` | codeberg.org, `forgejo.*`, `gitea.*` |
| Runner | Actions enabled | one that runs Docker images | Actions enabled, a runner labelled `docker` or the one [`runner`](#self-hosted-runners) names |
| Token | the run's `github.token` | `GITLAB_TOKEN` variable, `api` scope | the run's own token |
| Cloud roles over OIDC | GitHub's identity token | `id_tokens` | Forgejo 15 and Runner 12.5 or later |
| Require | `terragucci/plan` in branch protection | "Pipelines must succeed" | `terragucci/plan` in branch protection |
| Report | `terragucci-report` artifact of the run the note links | a job artifact the note links, plus the merge-request widget | `terragucci-report` artifact of the run the note links |
| Two pushes' applies | side by side | side by side | side by side, each push to the default branch in a group of its own commit |

Self-managed GitLab works the same. See [applies side by side](/terragucci/reference/pipeline/#applies-side-by-side).

## Self-hosted runners

```yaml
runner:
  default: [self-hosted, linux]
  apply: [self-hosted, prod]
```

Every job then asks for a runner with both labels of its stage: `runs-on` on GitHub and Forgejo, `tags` on GitLab. Here the apply jobs run on runners labelled `prod`, such as ones inside the network the apply role reaches, and every other job on the rest. `runner: [self-hosted, linux]` alone puts every job on one set. On GitHub, `group: <name>` picks a runner group.

Each job runs in terragucci's image, so the runner must start containers: Docker on a GitHub runner, the Docker executor on GitLab, a `docker://` label on Forgejo. Run `npx terragucci init` to write the labels in; [Runners](/terragucci/reference/config/#runners) has the rest.

## Agent features

Setup and every pull request feature are plain CI jobs that need no agent; four opt-in features run a model.

| CI jobs, no agent | Page |
|---|---|
| Setup with `init` (an agent can run it for you) | [Set up with a coding agent](/terragucci/getting-started/agents/) |
| The plan note and `terragucci/plan` status | [Get your first plan note](/terragucci/getting-started/) |
| Tips and policy checks | [Tips](/terragucci/reference/tips/), [Policy](/terragucci/reference/policy/) |
| A `/terragucci plan` re-plan; on GitLab through the `comments:` schedule | [Re-plan from a comment](/terragucci/guides/re-plan-from-a-comment/) |
| `/terragucci lock` and `/terragucci unlock` (GitHub, Forgejo, and GitLab with `comments:` and `apply.when: pull-request` set); `locks: plan` (GitHub and Forgejo) | [Locks](/terragucci/guides/apply-before-merge/#locks) |
| Apply before merge and `/terragucci apply` (GitHub, Forgejo, and GitLab with `comments:` set) | [Apply before merge](/terragucci/guides/apply-before-merge/) |
| Approvals in every mode, `terragucci approve` | [Approve a waiting wave](/terragucci/guides/approve-a-wave/) |
| A recorded policy override | [Override a policy denial](/terragucci/guides/approvals-runbook/#override-a-policy-denial) |
| Drift checks | [Turn on drift checks](/terragucci/guides/turn-on-drift-checks/) |
| Module publishing and rollouts | [Publish your modules](/terragucci/guides/publish-modules/), [roll out a version](/terragucci/guides/roll-out-a-module-version/) |

| Opt-in: coding agent | Off until | Page |
|---|---|---|
| The `/terragucci agent <ask>` comment (GitHub and Forgejo) | `agent.comment` is set, with a model API key secret | [Have an agent change a pull request](/terragucci/guides/agent-change-a-pull-request/) |
| A code change that matches what drift found, in a pull request (GitHub and Forgejo) | `agent.drift` is set, with a model API key secret | [Have an agent fix drift](/terragucci/guides/agent-fix-drift/) |
| A note comparing a pull request's description with its plan (on GitLab through the `comments:` schedule) | `review.agent` is set, with a model API key secret | [Have a model review a pull request](/terragucci/guides/agent-review-a-pull-request/) |
| A summary of a refused wave | you add its job by hand, with a model API key secret | [Have an agent summarize a refused wave](/terragucci/guides/agent-refused-wave/) |

## Prerequisites

| You need | For |
|---|---|
| Terraform or OpenTofu roots, or a Terragrunt, Atmos, Terramate or CDK Terrain repo | what `init` finds |
| Node.js 22 or later on your machine | running `init` |
| admin on the repo or project | the token, the cloud roles and the required status |

## Steps

1. Install terragucci and run `init` from the root of the repo.

   ```bash
   npm i -D @intentius/terragucci
   npx terragucci init
   ```

**GitHub**

   ```text
   found 15 roots in 2 layers, tofu 1.13.1 (tofu on the path), forge github (the origin remote (github.com))
   wrote .github/workflows/terragucci.yml
   no terragucci.yml needed (defaults fit)
   ```

**GitLab**

   ```text
   found 15 roots in 2 layers, tofu 1.13.1 (tofu on the path), forge gitlab (the origin remote (gitlab.com))
   wrote .gitlab/terragucci.yml
   wrote .gitlab-ci.yml
   no terragucci.yml needed (defaults fit)
   ```

   The jobs go in `.gitlab/terragucci.yml`, and `init` touches your `.gitlab-ci.yml` only like this:

   | Your `.gitlab-ci.yml` | `init` |
   |---|---|
   | none | writes one that includes `.gitlab/terragucci.yml` |
   | your own jobs | adds `- local: .gitlab/terragucci.yml` to its `include:` and keeps the rest (`updated .gitlab-ci.yml`) |
   | an `include:` that is one value, not a list | stops and names the entry to add |
   | its own `stages:` | stops unless the list has `.gitlab/terragucci.yml`'s stages (`check`, `plan`, `apply` and the rest) in that order, and names them |
   | a job named like one of terragucci's (`check`, `plan`, `apply-wave-1`) | stops: GitLab would merge the two jobs |

   With no `stages:` of your own, GitLab's default stages put your `build` and `test` jobs before terragucci's stages and `deploy` after the apply. Your top-level `variables:` and `default:` reach terragucci's jobs too.

**Forgejo**

   ```text
   found 15 roots in 2 layers, tofu 1.13.1 (tofu on the path), forge forgejo (the origin remote (codeberg.org))
   wrote .forgejo/workflows/terragucci.yml
   no terragucci.yml needed (defaults fit)
   ```

   For a host on another scheme or port, set `url` in `terragucci.yml`.

   Pass `--forge` once for a host the table does not list; `init` records it in `terragucci.yml`.

   In a Terragrunt repo `init` finds the units and writes the same files. [Use Terragrunt](/terragucci/guides/use-terragrunt/) covers the version, excludes and roles.

2. Give the pipeline a token.

**GitHub**

   The jobs use the run's `github.token`. The plan job adds `statuses: write` and `pull-requests: write` (and `actions: read` with a `drift` schedule) and runs only for pull requests from branches in the same repo, so a fork reaches no job with them.

**GitLab**

   Add `GITLAB_TOKEN` under Settings, CI/CD, Variables: a masked project access token with the `api` scope. `token_env` in `terragucci.yml` names another variable.

   | `terragucci.yml` | Plan job | Plan note | `GITLAB_TOKEN` |
   |---|---|---|---|
   | no `gitlab` key (the default) | holds the token, so a merge request's code can use it as the project's bot | posted by the plan job at once | a masked variable |
   | `gitlab: { token: protected }`, with `comments:` set | holds no token | posted by the comments schedule's job | a masked and protected variable, on a protected default branch |

   [The threat model](/terragucci/reference/threat-model/) says what each choice leaves open.

**Forgejo**

   Each run brings its own token; there is no secret to add.

3. Give the jobs cloud access. Set `oidc` in `terragucci.yml` and run `npx terragucci init` again:

   ```yaml
   oidc:
     plan_role: arn:aws:iam::111122223333:role/terragucci-plan
     apply_role: arn:aws:iam::111122223333:role/terragucci-apply
   ```

**GitHub**

   Each role's trust policy must accept your repo.

**GitLab**

   Roles come through `id_tokens`. GitLab-managed Terraform state limits concurrent inits, so fewer Terragrunt units run at once.

**Forgejo**

   OIDC needs Forgejo 15 and Forgejo Runner 12.5 or later; the jobs set `enable-openid-connect: true`. The issuer is your Forgejo URL plus `/api/actions`. Older versions serve no token; give their runner static credentials instead.

   [Environment variables and credentials](/terragucci/reference/environment/#cloud-roles-over-oidc) has the trust policies.

4. Commit, push and open a pull request.

**GitHub**

   ```bash
   git switch -c add-terragucci
   git add .github package.json package-lock.json
   git commit -m "Add terragucci"
   git push -u origin add-terragucci
   ```

**GitLab**

   ```bash
   git switch -c add-terragucci
   git add .gitlab .gitlab-ci.yml package.json package-lock.json
   git commit -m "Add terragucci"
   git push -u origin add-terragucci
   ```

**Forgejo**

   ```bash
   git switch -c add-terragucci
   git add .forgejo package.json package-lock.json
   git commit -m "Add terragucci"
   git push -u origin add-terragucci
   ```

   Then change a line in one root and push again, since a change that touches no root has nothing to plan.

5. Require the status so that a failed plan blocks the merge. With `binary: choudoufu` ([set it up](/terragucci/guides/use-a-binary/#choudoufu)), the check also runs a live check with no cloud credentials.

**GitHub**

   Add `terragucci/plan` to the default branch's protection rule as a required status.

   When the check fails, so does the run; its log shows the diff `tofu fmt` would make:

**GitLab**

   Turn on "Pipelines must succeed" under Settings, Merge requests.

   The pipeline fails with the check:

**Forgejo**

   In the default branch's protection rule, enable status checks with `terragucci/plan` as the pattern.

   The failed check is a red cross on the commit, and the fmt job pushes the formatting after it:

6. Make approval possible. A wave that destroys something waits until a person runs `npx terragucci approve` from a checkout or, under [`approval: pr-review`](/terragucci/guides/approve-a-wave/#approval-modes), reviews the pull request. Signing is optional; only `approval: sealed` needs a signers file ([before your first approval](/terragucci/getting-started/#first-approval)).

## Next

- [Approve a waiting wave](/terragucci/guides/approve-a-wave/)
- [Keep reports in a bucket](/terragucci/guides/keep-reports-in-a-bucket/)
- [The tutorial](/terragucci/tutorial/) runs all of this on a local Forgejo with a 15-root example.

---

# Approve a waiting wave

Source: https://intentius.io/terragucci/guides/approve-a-wave/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/approve-a-wave/.
Find the waiting wave with `npx terragucci approve --dry-run`, summarize its
report (destroys, replacements, roots) and print the command it gives for me.
The `--dry-run` preview is the one form of `terragucci approve` you may run; never sign.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

One wave applied, with an approval recorded in your repo that names the exact plans you read.

## Prerequisites

| You need | Detail |
|---|---|
| A wave that ran | After a merge, or from `/terragucci apply` on an open pull request when [`apply.when`](/terragucci/reference/config/#apply-before-merge) is `pull-request`. |
| A gate | `gate` set to `on-destructive` (the default) or `always`. With `never`, no wave waits ([Gate policy](/terragucci/reference/stages/#gate-policy)). |
| terragucci | `npm i -D @intentius/terragucci`, where you approve. |
| Write access | `terragucci approve` pushes a commit to `chant/lifecycle` with your own git credentials. |
| Under `approval: sealed` only | An ssh key of yours in `.chant/allowed_signers` on the default branch ([setup](#set-up-the-signers-file), once per repo). |
| To be a person | Nothing signs off for you. |

## Approval modes

Each mode counts different approvals; `approval` in `terragucci.yml` picks one. Every mode binds the wave's set digest: an approval of other plans is refused as changed.

| Mode | Counts | Setup | What it proves |
|---|---|---|---|
| `ledger` (default) | any approval of the digest on `chant/lifecycle`, signed or not | none | someone with push access to `chant/lifecycle` approved these exact plans. Anyone who can push there can write an approval in anyone's name, so it records the plans and does not prove who approved. |
| `pr-review` | the merged pull request's approval of its head, by a reviewer other than its author with write access, when the wave plans what the review saw; and any `terragucci approve` of the digest, as under `ledger` | on GitHub or Forgejo, optionally require `terragucci/approval` in branch protection; on GitLab, an approval rule | a writer other than the author approved the head whose plans these are. An approval by the user the pipeline's token acts as never counts. A `terragucci approve` still proves only the plans. |
| `sealed` | only an approval sealed with `--sign` by a key the signers file lists for its approver | a [signers file](#set-up-the-signers-file); `init` lists each wave under [`identity.gates`](/terragucci/concepts/glossary/#identitygates) | a listed person approved these exact plans |

A wave reads the mode at base, like the signers file ([Rule commit](#rule-commit)). `terragucci config check` prints the mode in force and its source.

| `terragucci.yml` | Mode in force |
|---|---|
| sets `approval` | that mode |
| sets none, and [`chant.workspace.json`](/terragucci/concepts/glossary/#chantworkspacejson) lists gates under `identity.gates` | `sealed`; set `approval: sealed` to say so, or `approval: ledger` and run `terragucci init` to drop the gates |
| sets none, and no gates are listed | `ledger` |

## Approve by review (`approval: pr-review`)

Works on every forge. GitLab's merge request approvals name no commit, so there an approval counts only after the merge request's latest push.

1. Open the pull request's plan note. Its waves table gives each wave's change digest (what the apply compares against) and whether the gate will hold it.

2. Read the plans, then approve the pull request on its head.

**GitHub**
       With write access, pick Files changed > Review changes > Approve.
**GitLab**
       As a member with the Developer role or higher, approve the merge request after its last push. Once withdrawn, it no longer counts.
**Forgejo**
       Under Files changed, choose Review > Approve. Only an official review counts; Forgejo makes a review official when its author can write to the repo.

   The author's own approval never counts. A review counts only on the commit it names, so a push after your review needs a fresh one; a latest review that asks for changes holds every wave back.

3. Keep unreviewed changes from merging.

   | Forge | Require |
   |---|---|
   | GitHub | `terragucci/approval` under Settings > Branches (or Rules) > the default branch > Require status checks. It is pending while a wave the gate will hold has no approving review of the head. |
   | Forgejo | `terragucci/approval` under Settings > Branches > the default branch's rule > Status check patterns, with the same meaning. |
   | GitLab | an approval rule under Settings > Merge requests (GitLab Premium and Ultimate); the pipeline posts no `terragucci/approval` there. |

4. Merge. After that, each gated wave plans the merge commit and checks its change digest against the one the note recorded for the reviewed head.

   | Digest at merge | What the wave does |
   |---|---|
   | same digest | records the approval on `chant/lifecycle` (`via: pr-review`, the pull request, its head and the reviewers) and applies |
   | another digest (the plans moved after the review) | applies nothing, exits 4 and prints the `terragucci approve` command for the new digest |
   | no row for the wave in the note, no approving review, or a direct push | waits for a `terragucci approve`, as under `ledger` |

5. A wave waiting for a review can still get one. On GitHub or Forgejo, approve the merged pull request on its head. GitLab takes no approval after the merge, so there the merge request needs it while still open. Then run the wave again ([step 4 below](#approve-from-a-checkout)): it finds the review and applies. With [`notify`](/terragucci/guides/notify-a-chat-channel/#approve-from-the-message-by-review) set, the waiting wave's chat message links the review page.

## Approve from a checkout

1. Find the waiting wave and its command.

   | Where | What it gives |
   |---|---|
   | the pull request's plan note, before the merge | each wave the gate will hold, with `terragucci approve wave-<k> --plan <digest>`; after the merge the wave asks for that digest unless its plans moved |
   | `terragucci/apply` on the commit | the waiting wave's command, as the status's description: pending on GitHub and Forgejo, failed on GitLab, which cannot move a running status back to pending |
   | the job's log, or a comment's reply | the same command; the job exits with code 3 |

   The screenshots come from [the tutorial's example](/terragucci/tutorial/waves/), which runs `approval: sealed`, so its commands carry `--sign` and its approvals a seal. Under the default `ledger` they carry neither.

**GitHub**

   The command is the last line of the job's log:

**GitLab**

   The job fails with the command at the end of its log:

**Forgejo**

2. Read what the wave will do.

   The wave waits because a plan destroys or replaces something, or because `gate` is `always`. Destroys and replacements are never grouped, so they sit at the top of the report, where you read each one.

3. Approve it from a checkout of the repo.

**ledger (default) or pr-review**
       ```bash
       npx terragucci approve wave-2 --plan jcs1-sha256:9f2c... --actor github:alice
       ```
**sealed**
       ```bash
       npx terragucci approve wave-2 --plan jcs1-sha256:9f2c... --actor github:alice --sign ~/.ssh/id_ed25519
       ```

       `--actor` must be your principal in `.chant/allowed_signers`. Left out, `--sign` uses git's `user.signingkey` when `gpg.format` is `ssh`.

   | `terragucci approve` | Does |
   |---|---|
   | with no flag | fetches `chant/lifecycle`, finds the waiting wave, prints its roots and destroys, and records an approval of the digest that wave planned |
   | `wave-<k>` | picks the wave when several wait |
   | `--plan <digest>` | the digest you read: approves only a wave waiting for exactly it, and otherwise approves nothing and exits 1, naming the digest waiting. Use it whenever you read the plans somewhere other than this command's own output, such as a chat message or the plan note. |
   | `--actor` | the name the approval records; pass it on your own machine, where it would otherwise record `$USER` |
   | `--sign` | seals the approval; the default under `approval: sealed` |
   | `--dry-run` | prints what it would approve and records nothing |
   | `--no-resume` | records the approval and starts nothing |

   The approval is one line appended to `_gates/tf-apply.jsonl` on `chant/lifecycle` in its own commit. The example runs `approval: sealed`, so its line is sealed:

4. Let the wave run again.

   `terragucci approve` restarts it with your forge token once the approval is recorded, and says so when it has no token.

   | Forge | Token `terragucci approve` reads |
   |---|---|
   | GitHub | `GH_TOKEN`, or `gh auth login` |
   | GitLab | `GITLAB_TOKEN` |
   | Forgejo | `FORGEJO_TOKEN` |

   With [`apply.resume`](/terragucci/reference/pipeline/#resume-after-an-approval) set, the resume job applies the wave within that many minutes of any approval. Re-run the wave by hand when `apply.resume` is unset, and after a pull request review under `approval: pr-review`:

   | Situation | How to re-run |
   |---|---|
   | `apply.when: merge` (the default), GitHub or Forgejo | Comment `/terragucci apply` on the merged pull request (add `wave-2` to stop after that wave), or re-run the job. Needs write access. |
   | `apply.when: merge`, GitLab | With `comments:` set, comment `/terragucci apply` on the merged merge request; the comments job retries the first apply job that did not succeed on its next run. `wave-<n>` is refused, since GitLab runs the waves after a retried one. Needs Developer or above. Without `comments:`, retry the job. |
   | `apply.when: pull-request` | Comment `/terragucci apply` on the open pull request again. The mode and the signers come from the default branch, so the pull request cannot relax them or add its own approver. The forge's review is also required. |

   The comment approves nothing.

   | The wave or comment | Outcome |
   |---|---|
   | a wave without an approval that counts in its mode | waits, with the command in the reply |
   | a wave whose plans changed after the approval, before they applied | refused |
   | a wave planning anew after its approved plans applied | waits for an approval of the new plans |
   | an approved wave | applies, resuming where it stopped |
   | a comment that fails a check | runs nothing; the reply names the check ([the checks](/terragucci/reference/pipeline/#ignored-comments)) |

   [Apply a merged pull request](/terragucci/guides/re-plan-from-a-comment/#apply-a-merged-pull-request) and [Apply before merge](/terragucci/reference/pipeline/#apply-before-merge) list what each refuses.

   In [the tutorial's example](/terragucci/tutorial/changed-wave/) (`approval: sealed`), the module bump's wave 4 was refused and its new plans approved. Then `/terragucci apply` on the merged pull request resumed the waves and wave 4 applied:

   The report then shows the wave as approved and links its record.

## Roots on HCP Terraform

terragucci's gate reads neither HCP Terraform's run approvals nor its locks, so set workspaces to local execution; remote execution adds HCP's own approvals and locks.

## Set up the signers file

Only `approval: sealed` reads it. With that key in `terragucci.yml`, `terragucci init` lists each wave under `identity.gates`, so `terragucci approve` seals by default.

1. In a reviewed pull request to the default branch, add `.chant/allowed_signers`, one line per approver, in ssh-keygen's allowed_signers format. `terragucci init --signer github:alice` writes the first line from your `git config user.signingkey` when the file does not exist yet:

   ```text
   github:alice ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...
   github:bob ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQ...
   ```

   | Line | Counts? |
   |---|---|
   | `ssh-ed25519` | yes |
   | `sk-ssh-ed25519@openssh.com` | yes |
   | `ssh-rsa` | yes |
   | `namespaces="..."` | only if it lists `chant-gate` or `*` |
   | `valid-after`, `valid-before` | ignored |
   | `cert-authority` | ignored |
   | a pattern principal (`*`, `?`, `!`) | ignored |

   To move the file, set its path in `.chant/trust.json`, e.g. `{"schema": 1, "signers": "security/allowed_signers"}`.

2. List only keys that people hold; leave out agent and CI job keys.

3. Protect `chant/lifecycle` against force pushes and deletion (next section).

### Rule commit

These rule files are read from base (the applied commit's first parent):

- the `approval` key in `terragucci.yml`
- the signers file
- `.chant/trust.json`
- `chant.workspace.json`

A pull request's change to them governs only later merges. One that switches `sealed` to `ledger` is still judged sealed.

| Merge method | Base is | Safe |
|---|---|---|
| Merge commit | the default branch before the merge | yes |
| Squash | the default branch before the merge | yes |
| Rebase of one commit | the default branch before the merge | yes |
| Rebase of several commits | the pull request's own next-to-last commit | no: merge with a merge commit or a squash |

| A change that turns sealing off for later merges | Applies when |
|---|---|
| `approval` set to `ledger` | always |
| `chant.workspace.json` deleted, or its `identity.gates` emptied | `terragucci.yml` sets no `approval` |

Give those changes the same review as the signers file; the [agent comment](/terragucci/reference/pipeline/#the-agent-comment) refuses both.

## Push access to `chant/lifecycle`

| Who pushes | What | With |
|---|---|---|
| an approver | approval records, as fast-forwards | their own credentials |
| the apply job | pending records | its token (`github.token`, or `GITLAB_TOKEN` on GitLab); on GitHub no rule can tell it from another workflow |

| Mode | What a pushed line counts for |
|---|---|
| `sealed` | nothing, unless its seal verifies against the signers file at base |
| `ledger` and `pr-review` | every line of the digest counts, so who can push here is who can approve |

Protection keeps history from being rewritten.

| Forge | Protect `chant/lifecycle` with |
|---|---|
| GitHub | a ruleset or protection rule blocking force pushes and deletion, with pull requests and status checks off. |
| GitLab | a protected branch with push and merge allowed to a role your approvers and `GITLAB_TOKEN` both hold, force push off. |
| Forgejo | a protected branch rule with push for everyone with write access and force push off. |

## Refused wave

A root whose plan changed between your approval and the apply makes the wave apply nothing ([Fix a refused wave](/terragucci/guides/fix-a-refused-wave/)). After a wave has applied, the next change waits for a new approval.

## Next

- [Approvals runbook](/terragucci/guides/approvals-runbook/)
- [Waves and approvals](/terragucci/concepts/waves-and-approvals/)
- [Approvals as records in your repo](/terragucci/concepts/approvals-as-records/)
- [The audit trail](/terragucci/reference/audit-trail/): who approved which digest, and the apply it let through

---

# Fix a refused wave

Source: https://intentius.io/terragucci/guides/fix-a-refused-wave/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/fix-a-refused-wave/.
Fetch both reports, run `npx terragucci respond wave-refused ... --json`,
and tell me in five lines which roots moved and why. The decision is mine.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

A decision on a refused wave: the new plan approved and applied, or the change that moved it removed.

## Prerequisites

| You need | Why |
|---|---|
| A wave that stopped with a refusal | the job says the set digest no longer matches its approval, and nothing in the wave applied |
| The apply job's log | unless `respond.wave-refused` is `off`, it prints the diff from step 3 |
| The job's artifact, `terragucci-report-apply-wave-<k>` | it holds both reports the diff compares |

## Steps

1. Understand why it refused.

   An approval binds a wave's set digest. The wave applies nothing if any root's plan changes between the approval and the apply. The usual cause is another merge touching a root in the wave, or a data source reading a new value. An approval the wave already applied under refuses nothing: the next plans wait.

   In [the tutorial's example](/terragucci/tutorial/changed-wave/), approve the waiting wave and then merge the module bump. Its job stops and names the roots that moved:

2. Get the two reports.

   The artifact `terragucci-report-apply-wave-<k>` holds the refused job's `terragucci-report/`, with the approved report in `approved/report.json` and the job's own in `current/report.json`. Fetch it to a local `terragucci-report/` directory.

**GitHub**
       ```bash
       gh run download <run-id> -n terragucci-report-apply-wave-2 -D terragucci-report
       ```
**GitLab**
       The `apply-wave-2` job's page > Job artifacts > Download, then unzip it in the checkout; the archive holds `terragucci-report/`.
**Forgejo**
       The run's page > Artifacts > `terragucci-report-apply-wave-2`, then unzip it into `terragucci-report/`.

   The approved report also stays on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) at `_gates/tf-apply/wave-<k>/<digest>.json` (`:` written as `_`):

   ```bash
   git fetch origin chant/lifecycle
   git show origin/chant/lifecycle:_gates/tf-apply/wave-2/jcs1-sha256_<hex>.json
   ```

3. Print the diff.

   ```bash
   npx terragucci respond wave-refused --approved terragucci-report/approved --current terragucci-report/current --wave 2
   ```

   It lists each root whose plan digest moved and what changed inside it. `--json` prints one envelope.

4. Decide.

   | Choice | Command | Result |
   |---|---|---|
   | Keep the new plan | `npx terragucci approve wave-2 --plan <digest>` from a checkout, with the new digest the job printed. It approves it, signs under `approval: sealed`, and restarts the wave ([Approve a waiting wave](/terragucci/guides/approve-a-wave/)) | The new plans apply. |
   | Drop it | Revert the change on the default branch. | The old approval does not come back: the refused run recorded a newer pending fact, so the wave waits for a fresh approval. |

An agent may [summarize the diff](/terragucci/guides/agent-refused-wave/), but it does not re-approve.

## Next

- [Approvals runbook](/terragucci/guides/approvals-runbook/)
- [Responses to pipeline events](/terragucci/reference/responses/#wave-refused)
- [Waves and approvals](/terragucci/concepts/waves-and-approvals/)

---

# Approvals runbook

Source: https://intentius.io/terragucci/guides/approvals-runbook/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/approvals-runbook/.
Run the "List the waves waiting" command with a read-only clone and tell me
each wave, digest and expiry. Do not revoke an approval, and do not run `terragucci override`.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

The commands an approver or on-call engineer runs. [Approve a waiting wave](/terragucci/guides/approve-a-wave/) walks through a first sign-off.

The ledger is `_gates/tf-apply.jsonl` on the [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) branch: a `"kind":"pending"` line is a wave asking, any other line an approval. Each waiting wave's report is at `_gates/tf-apply/wave-<k>/<digest>.json`. A wave that applies under an approval first marks it used in `_gates/tf-apply/applied.jsonl`; a used approval refuses no later plan.

## Choose a mode

| `approval` | An approval counts when | Setup |
|---|---|---|
| `ledger` (default) | it names the wave's digest. Anyone who can push to `chant/lifecycle` can write one in anyone's name; it records the plans and does not prove who approved. | none |
| `pr-review` | the merged pull request's head was approved by a writer other than its author and the wave plans what the review saw, or, as under `ledger`, it names the digest | none; optionally require `terragucci/approval` (GitHub, Forgejo) or an approval rule (GitLab) |
| `sealed` | it names the digest and its seal verifies against the signers file at base | [Set up signers](#set-up-signers) |

`terragucci config check` prints the mode in force and where it comes from. A wave reads it at base, so a change to it governs the merges after it.

| You have | You want | Do |
|---|---|---|
| `identity.gates` in `chant.workspace.json`, no `approval` key (sealed) | to keep signing | add `approval: sealed` to `terragucci.yml` |
| the same | unsigned approvals | add `approval: ledger` and run `terragucci init`, which drops the wave gates; or `terragucci init --approval ledger` |
| `ledger` | sealed approvals | add `approval: sealed`, run `terragucci init`, then set up signers |

## Set up signers

Only under `approval: sealed`, once per repo, in a reviewed pull request to the default branch.

1. Add `.chant/allowed_signers`, one line per approver in ssh-keygen's allowed_signers format; `terragucci init --signer <principal>` writes the first from `git config user.signingkey`. The first field is what the person passes as `--actor`:

   ```text
   github:alice ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...
   ```

2. Set `approval: sealed` and run `terragucci init`. It lists each wave's gate under [`identity.gates`](/terragucci/concepts/glossary/#identitygates) in [`chant.workspace.json`](/terragucci/concepts/glossary/#chantworkspacejson); then an approval counts only when its seal verifies against the signers file at base ([why](/terragucci/guides/approve-a-wave/#rule-commit)).

3. List only people in the file; leave out agents' and CI jobs' keys.

4. Add or remove a person by pull request. The change first governs the apply of the next merge.

## Approve a wave

A waiting wave exits with code 3; its command is in the job log, the `terragucci/apply` status and the pull request's plan note. Read the plans in the report, then, from a checkout:

**ledger (default) or pr-review**
    ```bash
    npx terragucci approve wave-2 --plan <digest> --actor github:alice
    ```
**sealed**
    ```bash
    npx terragucci approve wave-2 --plan <digest> --actor github:alice --sign ~/.ssh/id_ed25519
    ```

It records an approval of the planned digest and restarts the waiting wave (`--dry-run` prints what it would approve instead). If the restart fails, re-run the job. Commenting `/terragucci apply` on the pull request also works (an open one needs `apply.when: pull-request`). On GitLab the comment needs `comments:` set, and the comments job answers it on its next run.

## Approve by review

Under `approval: pr-review`, approve the pull request on its head before it merges; each gated wave then applies when it plans what the review saw ([the steps](/terragucci/guides/approve-a-wave/#approve-by-review-approval-pr-review)).

**GitHub**
    Files changed > Review changes > Approve, with write access.
**GitLab**
    As a Developer or higher, approve the merge request after its last push. An approval before a push counts for nothing.
**Forgejo**
    Files changed > Review > Approve, as an official reviewer.

On GitHub and Forgejo, `terragucci/approval` on the head then turns success. A wave whose plans moved after the review exits 4 with the `terragucci approve` command for the new digest. A review's ledger line carries `"via": "pr-review"` beside the pull request and its head and reviewers.

## Override a policy denial

This needs [`policy.override`](/terragucci/reference/policy/#overriding-a-denial) at base.

1. The denied wave exits 1. Its log gives the `terragucci override` command for each root the policy denied.

2. Read the root's plan and denial in the wave's report.

3. As a person the key lists, run the command in a checkout:

**ledger (default) or pr-review**
       ```bash
       npx terragucci override envs/prod/app --rule main.deny_public_bucket \
         --reason "the incident needs the bucket public until 18:00" --actor github:alice
       ```
**sealed**
       ```bash
       npx terragucci override envs/prod/app --rule main.deny_public_bucket \
         --reason "the incident needs the bucket public until 18:00" --actor github:alice --sign ~/.ssh/id_ed25519
       ```

   `--dry-run` prints what it would override and records nothing.

4. Re-run the wave's job.

| The wave then | Because |
|---|---|
| applies the root, and its report names the override | the override names this plan and these rules, and its author is listed at base |
| exits 1 again, naming why the override does not count | its author is not listed, it gives no reason, or under `sealed` its seal does not verify |
| exits 4 and applies nothing | the plan or its rules changed before any run applied the override; the next run records the new denial to override |
| exits 1 with a new `terragucci override` command | a run applied the override, and the root's plan changed since: the new plan needs its own override |

The ledger is `_gates/policy-override.jsonl`, one gate per root. Overrides that went out are listed in `_gates/policy-override/applied.jsonl`, so a changed plan of that root asks for a fresh override. Revoke an override like an approval, by deleting its line before the wave runs.

## List the waves waiting for an approval

This prints each gate whose newest pending record has no approval of its digest after it:

```bash
git fetch origin chant/lifecycle
git show origin/chant/lifecycle:_gates/tf-apply.jsonl | jq -s -r '
  . as $all
  | ($all | map(select(.kind == "pending")) | group_by(.gate) | map(max_by(.timestamp))[]) as $p
  | select(($all | map(select(.kind != "pending" and .gate == $p.gate and .planDigest == $p.planDigest and .timestamp >= $p.timestamp)) | length) == 0)
  | "\($p.gate)\t\($p.planDigest)\texpires \($p.expiresAt)\t\($p.description)"'
```

A line past its `expires` time was recorded more than 48 hours ago; the wave's next run records a fresh one.

## Revoke an approval before its wave runs

Every approver can push to `chant/lifecycle`. Remove the approval's line in a normal commit; it works with force pushes blocked ([branch protection](/terragucci/guides/approve-a-wave/#push-access-to-chantlifecycle)).

1. Clone the branch:

   ```bash
   git clone --branch chant/lifecycle --single-branch <your repo url> lifecycle
   cd lifecycle
   ```

2. Delete the approval's line from `_gates/tf-apply.jsonl`.

3. Push the commit:

   ```bash
   git commit -am "revoke the approval of wave-2" && git push origin chant/lifecycle
   ```

The wave waits again; the old line stays in history.

## Recover from a refusal

A wave whose plans moved after an unapplied approval applies nothing and exits 4. The job names the moved roots; `terragucci respond wave-refused` prints what changed. Approve the new digest or revert. New plans after an applied approval wait for their own instead.

A revert does not revive the old approval: the refused run recorded a newer pending fact, so the wave needs a fresh [`terragucci approve`](/terragucci/reference/cli/#approve). See [Fix a refused wave](/terragucci/guides/fix-a-refused-wave/).

## Expiry

| Record | Expires | Stops counting when |
|---|---|---|
| Pending fact | 48 hours after the first run recorded it; the next run after that records a fresh one. | It is replaced by a newer pending fact for the gate. |
| Approval | Never. | It is older than the gate's newest pending fact, or names a digest the wave no longer plans ([Fix a refused wave](/terragucci/guides/fix-a-refused-wave/)); or, under `sealed`, its approver leaves `.chant/allowed_signers`, for merges made after that. Once a run applied under it, it refuses nothing. |
| Policy override | Never. | It is older than the root's newest recorded denial, or names another plan or other rules; or its author leaves `policy.override`, or under `sealed` the signers file, for merges made after that. |

## Next

- [Waves and approvals](/terragucci/concepts/waves-and-approvals/)
- [Gate policy](/terragucci/reference/stages/#gate-policy)
- [Threat model](/terragucci/reference/threat-model/#approval-modes): what each approval mode stops

---

# Re-plan a pull request from a comment

Source: https://intentius.io/terragucci/guides/re-plan-from-a-comment/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/re-plan-from-a-comment/.
Check that the default branch's pipeline has the comment trigger (on GitLab, the `comments` job and a pipeline schedule with TERRAGUCCI_SCHEDULE set to comments); if it does not, run `npx terragucci init` and open a pull request with the result.
You may comment `/terragucci plan` on a pull request and report what the note says.
Never comment `/terragucci apply`, `/terragucci lock` or `/terragucci unlock`.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

`/terragucci plan` on a pull request plans it again and updates its plan note and `terragucci/plan` status. `/terragucci plan envs/dev/orders` plans that root alone.

## Prerequisites

| You need | Why |
|---|---|
| The [pipeline](/terragucci/getting-started/) with the comment trigger | comment workflows run from the default branch; to add it, run `npx terragucci init` again and merge the result |
| Write access to the repo, for whoever comments (on GitLab, the Developer role or above) | anyone else gets no answer and no plan |

**GitHub**
Each new pull request comment starts the `replan` job.
**GitLab**
GitLab starts no pipeline for a merge request note. A pipeline schedule polls for notes instead and answers each on its next run.

| Step | What to do |
|---|---|
| Turn it on | add `comments: "*/5 * * * *"` to `terragucci.yml`, run `npx terragucci init`, and merge the result; the pipeline gets a `comments` job |
| Add the schedule | under CI/CD, Schedules: the same cron, the default branch, and the variable `TERRAGUCCI_SCHEDULE` set to `comments` |
| The token | `GITLAB_TOKEN` (or the `token_env` variable): a project access token with the `api` scope and the Developer role, in a masked variable |

The `comments` job runs from the default branch and holds no cloud credentials. It reads notes and calls GitLab's API: `/terragucci plan` starts a new merge request pipeline, whose plan job updates the plan note. Each reply carries a marker, so a note is answered once.
**Forgejo**
As on GitHub.

## Steps

1. Comment on the pull request with this line alone:

   ```text
   /terragucci plan
   ```

   The optional word after `plan` is a root path from the repository root.

2. Read the note. The `replan` job plans the head with the read-only role and no forge token, and the `replan-note` job updates the same note and status.

**GitHub**

**GitLab**

   When the pipeline the `comments` job started has planned, it edits the note:

**Forgejo**

   The example's note, updated in place above the comment:

   A named root the change does not reach gets a "not affected" reply and no update; a name that is not a root is refused with the list of roots:

## Re-plans by dispatch

A chat front end or a script can re-plan without a comment. On GitHub and Forgejo the workflow takes a `workflow_dispatch`:

| Input | Value |
|---|---|
| `pr` | the pull request's number; left empty, the dispatch runs the drift job where `drift:` is set |
| `root` | optional: one root path, read by the comment grammar |

The re-plan runs the same checks as `/terragucci plan [root]` and updates the same note and status.

**GitHub**

```sh
gh workflow run terragucci.yml -f pr=42 -f root=envs/dev/orders
```

The decision step asks the API for the dispatcher's permission and plans nothing without write access.

**GitLab**

GitLab has no dispatch with inputs. Run a new merge request pipeline instead (Run pipeline on its Pipelines tab), or call the API:

```sh
curl -X POST -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$CI_API_V4_URL/projects/<id>/merge_requests/<iid>/pipelines"
```

It needs the Developer role or above, and plans the whole merge request.

**Forgejo**

```sh
curl -X POST -H "Authorization: token $FORGEJO_TOKEN" -H 'content-type: application/json' \
  -d '{"ref":"main","inputs":{"pr":"42"}}' \
  "https://forgejo.example.com/api/v1/repos/acme/infra/actions/workflows/terragucci.yml/dispatches"
```

Forgejo answers 403 to a dispatcher without write access and starts no run. Its dispatch event carries no permission to read, so that refusal is the check.

## Comment forms

The text is untrusted and never reaches a script. `terragucci comment` reads it from the event file, or on GitLab from the API. Only one line in one of these forms is accepted; anything else is refused with the reason.

| Comment | Runs | Where | GitLab, with `comments:` set |
|---|---|---|---|
| `/terragucci plan` | a re-plan | every GitHub and Forgejo pipeline | a new merge request pipeline |
| `/terragucci plan <root>` | a re-plan of that root, which must be exactly a root the pipeline knows | every GitHub and Forgejo pipeline | the root is checked, and the whole merge request is planned |
| `/terragucci apply` | the approved waves | merged pull requests; open ones with `apply.when: pull-request` | merged merge requests: a retry of the merge commit's first apply job that did not succeed; with `apply.when: pull-request`, open ones: an `mr-apply` pipeline on the default branch |
| `/terragucci apply wave-<n>` | the approved waves up to wave n | as above | an open merge request with `apply.when: pull-request`; otherwise refused, since GitLab runs the waves after a retried job by itself |
| `/terragucci lock` | locks on the roots (in a Terragrunt repo, the units) this pull request reaches, with no apply | `apply.when: pull-request` or `locks: plan` | `apply.when: pull-request`, through `mr-apply`; otherwise answered as unsupported |
| `/terragucci unlock` | a release of this pull request's locks | `apply.when: pull-request` or `locks: plan` | as `lock` |
| `atlantis plan [-d <dir>]`, `atlantis apply` | the same as `/terragucci plan [<root>]` and `/terragucci apply`, with the same checks | `atlantis_comments: true` | the same, with `atlantis_comments: true` |
| `/terragucci agent <ask>` | a coding agent's change | `agent.comment` set; see [Have an agent change a pull request](/terragucci/guides/agent-change-a-pull-request/) | with `agent.comment` set, starts the agent's pipeline on the default branch; otherwise answered that it is off |

No comment approves, and a re-plan cannot change what an approval binds. [When a comment runs nothing](/terragucci/reference/pipeline/#ignored-comments) lists every check each command must pass. A refusal is a reply that starts with `terragucci:`.

| Case | Job |
|---|---|
| a comment that asks for nothing | ends cleanly |
| a forge 403 or failure, or an unreadable event file | fails, with the cause in the log |

## Apply a merged pull request

On a merged pull request, `/terragucci apply` re-runs `tf-apply` for the waves approved as [Approve a waiting wave](/terragucci/guides/approve-a-wave/) shows.

| Part | What happens |
|---|---|
| Workflow | `apply-comment` runs the default branch's workflow at the merge commit, never the head |
| Checks | `terragucci comment-apply` checks the comment before any credential, against the [merged-PR column](/terragucci/reference/pipeline/#ignored-comments) |
| Credentials | the job assumes `oidc.apply_role`, beside any push's apply |
| Another run's resources | with [choudoufu](/terragucci/concepts/glossary/#choudoufu), a wave that changes a resource another run is applying is refused; the reply names that run, and you comment again once it is done |
| Waves | from wave 1 until one does not apply; `wave-<n>` stops after wave n |
| A waiting wave | waits as on a push |
| A refused wave | prints its diff (`respond.wave-refused`) |
| A failed wave | prints its triage (`respond.apply-failed`) |
| [Terragrunt](/terragucci/guides/use-terragrunt/) | the same job and refusals; each wave runs `tf-apply --terragrunt` on its units from the merge commit |

| On GitLab | |
|---|---|
| `/terragucci apply` | retries the waiting wave's job in the merge commit's pipeline |
| The gate | `stage tf-apply` decides it again, so a wave with no approval waits again; the waves after it follow, each behind its own gate |
| A merge commit a later apply superseded | refused, as on GitHub |

## Apply an open pull request

With [`apply.when: pull-request`](/terragucci/reference/config/#apply-before-merge), `/terragucci apply` on an open pull request applies its head before merge. [Apply a pull request before it merges](/terragucci/guides/apply-before-merge/) has the steps.

Anyone with write access can lock or unlock, and the reply names what was locked or released. [Locks](/terragucci/guides/apply-before-merge/#locks) lists everything that takes and releases one.

| Comment | Does | Refused when |
|---|---|---|
| `/terragucci lock` | locks the roots the pull request reaches, applying nothing, so no other pull request applies them first; needs no approval or checks | another open pull request holds one of those roots; the reply names it |
| `/terragucci unlock` | releases the pull request's locks so another can apply those roots; under [`locks: plan`](/terragucci/reference/config/#plan-locks) it locks again on its next push or `/terragucci plan` | |
| `/terragucci plan`, under `locks: plan` | takes the locks again once a holder is gone | |

## Next

- [Approve a waiting wave](/terragucci/guides/approve-a-wave/) is the one place an approval is given.
- [Stages](/terragucci/reference/stages/) lists what `tf-plan` reads and writes.

---

# Apply a pull request before it merges

Source: https://intentius.io/terragucci/guides/apply-before-merge/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/apply-before-merge/.
Add `apply.when: pull-request` to terragucci.yml, run `npx terragucci config check --json` and `npx terragucci init`, and open a pull request with the result.
List the merge token and the branch protection I must set; do not create tokens or change branch protection yourself.
Never comment `/terragucci apply`, `/terragucci lock` or `/terragucci unlock`.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

An open change that applies from its head in the same waves and gates as a merge. It merges once every wave applied, and the push after the merge applies nothing.

## Prerequisites

| You need | Why |
|---|---|
| Plain roots or a Terragrunt repo on GitHub, GitLab or Forgejo, set up as in [Get your first plan note](/terragucci/getting-started/) or [Use Terragrunt](/terragucci/guides/use-terragrunt/) | the pipeline `init` writes holds the jobs below |
| On GitLab, [`comments:`](/terragucci/guides/re-plan-from-a-comment/) and its pipeline schedule | a merge request note starts no pipeline; the `comments` job reads `/terragucci apply` |
| Branch protection on the default branch that requires a review | the review is the guard: the applying job runs the change's code with the apply role |
| The [trade](/terragucci/reference/config/#apply-before-merge) accepted | [what the pull request's code can reach](/terragucci/reference/pipeline/#pull-request-code-access) with the apply role |

## Steps

1. Add the `apply` block to `terragucci.yml`:

   ```yaml
   apply:
     when: pull-request
     merge: auto      # or manual, the default, to merge by hand
     merge_token_env: MERGE_TOKEN
   ```

   Leave `waves.jobs` unset, since `config check` refuses it with `apply.when: pull-request`.

   With `merge: auto`, add that secret, holding a token of a user who may push to the default branch. Only `pr-merge`, which runs none of the change's code, gets it.

**GitHub**
   The token is optional. Without it the merge uses the job's own token and starts no `confirm`; the next push confirms it.
**GitLab**
   It is required, under `merge: manual` too. The `comments` job starts the apply pipeline on the default branch with it, and only a token allowed to merge there may. Add `forge: gitlab` and `comments:` beside the block.

   | Variable setting | Value |
   |---|---|
   | Key | the name `merge_token_env` gives, such as `TERRAGUCCI_MERGE_TOKEN` |
   | Value | a project access token with the `api` scope and a role the default branch's protection allows to merge |
   | Protected, Masked | on: only default-branch pipelines read it |
   | Environment scope | `terragucci-merge`: only `comments` and `pr-merge` name that environment, and neither runs the change's code |

   Under Settings, CI/CD, Variables, the minimum role allowed to use pipeline variables must include that token's role: the apply pipeline is started with variables naming the merge request.
**Forgejo**
   It is required, since Forgejo refuses a merge made with the job's own token.

2. Run `npx terragucci init` and merge the result in its own pull request. Nothing changes until it lands; after that, default-branch commits run `confirm` instead of the apply waves.

3. Open the change as usual and get its head approved on the forge by a reviewer other than its author. A push after the review needs a fresh approval.

4. Comment `/terragucci apply`. The reply names any failed check from the [open-PR column](/terragucci/reference/pipeline/#ignored-comments).

   | Check (`apply.requires`) | Fails when | Fix |
   |---|---|---|
   | `approved` | no reviewer other than the author approved the head, or a reviewer's last review asks for changes | get the head approved; a push needs a fresh approval |
   | `undiverged` | the head is behind the default branch | merge or rebase the default branch in, then get a new plan and approval |
   | `mergeable` | the forge says it does not merge: conflicts with the default branch, or on GitHub a branch protection rule blocks it | resolve the conflicts, or meet the rule |
   | `checks` | a status or check on the head failed or has not passed yet | fix and push, or wait for it |

   [`apply.requires`](/terragucci/reference/config/#apply-before-merge) picks which of the four the comment needs; all four by default. Whatever it lists, the comment also needs:

   - `terragucci/plan` passing on the head
   - the pipeline file left unchanged
   - each root the change reaches free of another open pull request's lock

5. Approve a waiting wave. A wave the `gate` policy holds stops, and the reply gives the command that approves it ([Approve a waiting wave](/terragucci/guides/approve-a-wave/)). Then comment `/terragucci apply` again.

6. Merge. `merge: auto` merges after the last wave and releases the locks; under `manual` they hold until you merge. A run that stopped at a wave never merges.

**GitHub**

**GitLab**

**Forgejo**

   After the merge, `confirm` plans every root (every unit in a Terragrunt repo). Its `terragucci/apply` status passes when nothing plans a change.

## On GitLab

GitLab builds a merge request's pipeline from its own `.gitlab-ci.yml`, so nothing applies there; the apply runs in a default-branch pipeline.

| Step | Job | What happens |
|---|---|---|
| 1 | `comments`, on its schedule | reads a Developer's `/terragucci apply`, `lock` or `unlock` note on an open merge request; for `apply`, checks `apply.requires` and refuses by name |
| 2 | `comments` | starts a pipeline on the default branch with the merge token and `TERRAGUCCI_MR`, `TERRAGUCCI_NOTE` and `TERRAGUCCI_HEAD` |
| 3 | `mr-apply`, from the default branch's pipeline file | reads the merge request and the note again from GitLab, refuses a head other than the merge request's, checks every requirement again and takes the locks |
| 4 | `mr-apply` | applies the head wave by wave with the apply role, behind the same gates, and replies |
| 5 | `pr-merge`, with `merge: auto` | merges once the reply says every wave applied |

`approved` needs an approval given after the latest push by a Developer or above who is not the author. `mr-apply` posts no status on the head; its replies say what happened. A note is answered on the schedule's next run.

## Config source

The apply of an open change takes its settings from the default branch. Edits to `terragucci.yml` in the change count only once it merges.

| Setting | Read from |
|---|---|
| Waves, `binary`, `gate`, `canary`, the apply role | the default branch's pipeline |
| `policy` and the policy directory | the default branch; if it has no `policy` key, a change adding one is checked against its own |
| `approval`, the gate rule ([`identity.gates`](/terragucci/concepts/glossary/#identitygates) in [`chant.workspace.json`](/terragucci/concepts/glossary/#chantworkspacejson)) and the signers file | the default branch |
| `reports`, `telemetry`, `parallelism` and every other key of `terragucci.yml` | the default branch |
| `respond` | the default branch; if unreadable, no response |
| The roots, units, modules and code that plan and apply | the change's head |

An unreadable default-branch config fails the wave before anything applies.

## Locks

Pull request locks hold roots. With `binary: choudoufu` ([set it up](/terragucci/guides/use-a-binary/#choudoufu)), a killed apply leaves no state lock behind ([locking with choudoufu](/terragucci/concepts/locking-and-staleness/#with-choudoufu)).

| Event | Lock |
|---|---|
| The change applies | each root it reaches is locked |
| `/terragucci lock` on the change, by anyone with write access (on GitLab, a Developer or above) | each root it reaches is locked, and nothing applies; the reply names the roots |
| With [`locks: plan`](/terragucci/reference/config/#plan-locks), the change is opened, pushed to or re-planned with `/terragucci plan` | each root its head reaches is locked; roots it no longer reaches are released; `terragucci/lock` passes, naming them |
| Another change reaches a locked root | refused; the reply names the root and the holder, and with `locks: plan` its `terragucci/lock` fails |
| The holder merges or closes | released |
| `/terragucci unlock` on the holder, by anyone with write access | released; the reply names what it released |

A second pull request that reaches a locked root is refused, and `/terragucci unlock` on the holder releases it:

A plan lock refusal is not queued: comment `/terragucci plan` on the refused change after the holder's locks are released.

In a Terragrunt repo the locks are on units. terragucci works them out from git without running Terragrunt:

| The change touches | Locked |
|---|---|
| a file in a unit's directory | that unit, and every unit whose `dependency` or `dependencies` block names it by a plain path, followed through |
| a file in no unit's directory, such as `root.hcl` or a module | every unit; the reply says which file |
| Markdown files only | nothing |

A Terragrunt change applies its waves of units from the head, one dependency layer at a time, so a unit applies before the units that read its outputs.

In an Atmos repo the locks are on instances, worked out from git without running Atmos:

| The change touches | Locked |
|---|---|
| a file in a component's directory | the instances of that component, and every instance that depends on one |
| a stack manifest, a catalog or `atmos.yaml` | every instance; the reply says which file |
| Markdown files only | nothing |

With `synth`, such as a CDK Terrain app, the locks are on the stacks the command writes. Git holds none of them, and the command is the pull request's own code, so terragucci does not run it to see which stacks a change reaches:

| The change touches | Locked |
|---|---|
| any file but Markdown, such as `main.js` | every stack; the reply says which file |
| Markdown files only | nothing |

## Next

- [The generated pipeline](/terragucci/reference/pipeline/#apply-before-merge) lists the jobs, the checks and the credentials.
- [Re-plan a pull request from a comment](/terragucci/guides/re-plan-from-a-comment/) has every comment command.

---

# Roll out a new module version

Source: https://intentius.io/terragucci/guides/roll-out-a-module-version/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/roll-out-a-module-version/.
Run `npx terragucci rollout <module>` (the preview only), fix any pin it refuses
in a pull request, and print the `--mode apply` command for me to run.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

Every root that pins the module moved to the new version through one pull request per wave.

## Prerequisites

| You need | Why |
|---|---|
| Roots that pin the module exactly by `oci://` tag or digest, registry `version` or git tag | a range cannot move ([Stages](/terragucci/reference/stages/#rolling-out-a-module-version) lists the cases) |
| The new version published ([Publish your modules](/terragucci/guides/publish-modules/)) | the rollout pins roots to it |
| The HCL parser beside terragucci: `npm i -D @cdktn/hcl2json` | the rollout edits each root's pin with it |
| A forge token that can open pull requests, in the variable `token_env` names | the apply run and the rollout job open the rollout's pull requests with it |
| Optional: `waves.canary` in `terragucci.yml` | it picks the roots that move first |
| Optional: `rollouts` in `terragucci.yml` | a scheduled job opens each next wave, so nobody runs step 5 |

## Steps

1. Preview the rollout.

   ```bash
   npx terragucci rollout modules/network
   ```

   Name the module by path or by source without the pin, and leave out the version to get the newest published. The dry run changes nothing. When pins disagree, `--from` picks which moves.

   For a module that [`modules.registry`](/terragucci/guides/publish-modules/#serve-a-module-registry) publishes, `modules/network` also names the calls whose `source` is its registry address, such as `modules.example.com/acme/network/generic`, and their `version` moves. With no version named, the newest the registry lists counts too.

2. Fix any pin it refuses. The preview lists each pin it cannot move, with a tip:

   | The pin | Tip |
   |---|---|
   | a range such as `~> 1.4` | `rollout-floating-pin`: pin one version |
   | set from a variable or a local | `rollout-literal-pin`: write a literal, since a variable's value is not in the diff |
   | absent from the source | `rollout-pin`: add a `?ref=`, `?tag=` or `version` |
   | two versions of the module in one directory | `rollout-one-pin`: pin every call at one version |

   Do that in its own pull request, then run the preview again.

3. Open the first wave.

   ```bash
   npx terragucci rollout modules/network 1.4.0 --mode apply
   ```

   `--mode apply` writes to the forge and runs no `terraform apply`; roots apply after the merge. It opens one pull request for the canary wave, or the first in dependency order. Only that wave's files change, and each pin keeps its shape.

4. Review and merge it. The apply stage runs on the merge commit.

5. Let the next wave open. With `rollouts` set, `init` writes a job that runs `terragucci respond rollout --mode apply` on that schedule:

   ```yaml
   rollouts: "*/15 * * * *"
   token_env: ROLLOUT_TOKEN
   ```

   Each run opens the next wave of every rollout whose last wave merged and applied, so a wave opens within one interval. A rollout with a pull request still open, or one closed unmerged, is left alone.

   | Forge | Job | Token | Schedule |
   |---|---|---|---|
   | GitHub | its own workflow, `terragucci-rollout.yml`, which you can also start by hand | the secret `token_env` names, else the job's own; GitHub runs no workflow for a pull request the job's own token opens, so name a secret holding a token that can push branches and open pull requests | the `rollouts` cron |
   | Forgejo | the same | the secret `token_env` names, else the job's own | the `rollouts` cron |
   | GitLab | the `rollout` job in the pipeline | the `token_env` variable | a pipeline schedule with that cron and the variable `TERRAGUCCI_SCHEDULE` set to `rollouts`; `init` prints the steps |

   `token_env` is the project's forge token variable, shared beyond the rollout: on GitLab every job that pushes or opens a merge request reads it, and on GitHub and Forgejo the fmt, tips, version-bump and drift jobs export their own token under that name. `respond.rollout: off` leaves the rollout job out.

   Without `rollouts`, run the rollout again after each merge. Each run takes at most one step:

   ```bash
   npx terragucci rollout modules/network 1.4.0 --mode apply
   ```

   Either way, the next wave waits for the last to merge and apply. The apply status it checks is `apply/<path>` per directory, else `terragucci/apply`. A pull request closed unmerged or a failed apply stops the rollout. It never merges or writes a default branch.

   | Exit code | Meaning |
   |---|---|
   | 0 | a step was taken, or the rollout is complete |
   | 3 | a pull request waits for a merge or an apply |
   | 1 | the rollout stopped |

   From a [control repo](/terragucci/concepts/control-repo/), wave 1 holds every project's canaries and later waves follow in config order. Each project gets its own pull request per wave. `rollouts` is a single repo's key, since a project's pipeline sees only its own roots; in a control repo, run `terragucci respond rollout --mode apply` on a schedule of your own.

## Provider upgrades

The same flow moves a provider in the lock file:

```bash
npx terragucci rollout --provider hashicorp/aws 6.68.0 --mode apply
```

Each lock file is rewritten for that provider alone, and an exact `version` constraint moves too. The wave stops unless every other provider stays where it was.

## Next

- [Tips](/terragucci/reference/tips/) names setups that make rollouts hard.
- [The JSON output of rollout](/terragucci/reference/cli-json/#rollout) lists each wave's state for scripts.

---

# Publish your modules

Source: https://intentius.io/terragucci/guides/publish-modules/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/publish-modules/.
Add the `modules:` block, run `npx terragucci publish --dry-run`, show me what
would be published, run `npx terragucci init`, and open a pull request. List the
registry credentials I must add; do not add them. If I ask for attested
releases, add `attest: true` and tell me to run `cosign generate-key-pair`
myself; never create, read or commit a private key.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

Every module that changed on the default branch released under a new number, each with a digest your roots can pin.

Each level is opt-in:

| Level | Config | What it adds |
|---|---|---|
| Publish | `modules.publish` | a git tag or OCI tag per release, pinned rollouts by pull request, and version bump jobs |
| Registry | `modules.registry` | each release as a module registry's files in a bucket or a Pages site, so roots use registry sources and version constraints |
| Test | `modules.test: true` | `tofu test` or `terraform test` on each module before a release of it publishes |
| Attest | `modules.attest: true` as well | a signature, SLSA provenance and an SBOM for each release, and a record of it in the release ledger |

## Prerequisites

| You need | Why |
|---|---|
| Modules in one place, such as `modules/network` and `modules/service` | each directory there is published on its own |
| Conventional commit messages | they decide the version bump |
| An OCI registry, or permission to push git tags to `origin` | where the versions go; Terraform has no OCI sources, so its roots pin a git tag |

## Steps

1. Name the modules and where they go in `terragucci.yml`.

   ```yaml
   modules:
     path: modules/*
     publish: oci://registry.example.com/acme/modules
   ```

   `publish` takes an `oci://` registry address, `git-tags`, or a list of both.

   | Target | Roots pin | Credentials |
   |---|---|---|
   | `oci://` registry | OpenTofu roots, by tag or `@sha256:` digest | the registry variables in step 4 |
   | `git-tags` | Terraform roots, by git tag | none; the tags are pushed to `origin` |

2. Preview.

   ```bash
   npx terragucci publish --dry-run
   ```

   The output lists each changed module and its next version under the [version bump rules](/terragucci/reference/stages/#version-bump-rules). For commits with no conventional type, see [`respond.version-bump`](/terragucci/reference/responses/#version-bump).

3. Add the publish job.

   ```bash
   npx terragucci init
   ```

   That adds a `publish` job, which runs with full history after `apply` on each push to the default branch.

4. Give it registry credentials; no other job gets them.

**GitHub**
       Repository secrets.
**GitLab**
       Protected, masked CI/CD variables.
**Forgejo**
       As on GitHub, repository secrets.

   | Variable | Holds |
   |---|---|
   | `TERRAGUCCI_REGISTRY_USER` | the registry user |
   | `TERRAGUCCI_REGISTRY_PASSWORD` | its password or token |
   | `TERRAGUCCI_REGISTRY_INSECURE` | `1` for a registry without TLS |

5. Merge a change to a module.

   The next push to the default branch publishes, printing each version's OCI manifest digest for a root to pin: `oci://registry.example.com/acme/modules/network@sha256:...`.

   With `git-tags`, each version is a tag on the repo, `<module>/v<version>`. Here `modules/service` moved to `0.2.0` after a change while `modules/queue` stayed at `0.1.0`:

   A published version never changes, so a rerun publishes nothing. Git-tag publishing fetches `origin`'s tags first; different content under an existing tag stops the run and names the tag.

## Test each release

With `modules.test`, the publish job runs the binary's `test` on each module before releasing it. A module with no test files or with failing tests is refused; the other modules still publish, and the job fails at the end.

```yaml
binary: tofu
modules:
  path: modules/*
  publish: git-tags
  test: true
```

The test files are the binary's own: `*.tftest.hcl` (and `*.tofutest.hcl` for OpenTofu) in the module or in its `tests` directory.

```hcl
# modules/network/tests/main.tftest.hcl
variables {
  name = "dev"
}

run "names" {
  command = plan

  assert {
    condition     = terraform_data.net.input == "dev"
    error_message = "the name is not passed through"
  }
}
```

The job runs `init -backend=false` and then `test` in the module's directory. The forge token, signing key and registry credentials are withheld from it. A refused release says why, with the end of the binary's output when a test failed:

```text
network 1.1.0: refused, not published to git-tags (modules/network has no tests (no *.tftest.hcl in it or its tests directory), and modules.test publishes only a release whose tests pass)
```

`publish --dry-run` runs no tests; it says which releases it would test.

## Serve a module registry

With `modules.registry`, a bucket or a Pages site also serves each release as static files in the [module registry protocol](https://opentofu.org/docs/internals/module-registry-protocol/). Roots call the modules by registry address, with a `version` that can be a constraint:

```hcl
module "network" {
  source  = "modules.example.com/acme/network/generic"
  version = "~> 1.0"
  name    = "dev"
}
```

1. Name the bucket, the address that serves it, and the namespace.

   ```yaml
   modules:
     path: modules/*
     publish: git-tags          # optional; the registry can stand alone
     test: true
     registry:
       bucket: s3://acme-modules
       url: https://modules.example.com
       namespace: acme
   ```

   | Setting | Default | Holds |
   |---|---|---|
   | `url` | required | the `https://` address that serves the files, with no path. Terraform and OpenTofu look for a registry at its host's root, over HTTPS only. Its host starts each module's source |
   | `namespace` | required | the namespace modules go under |
   | `bucket` or `dir` | one is required | an `s3://`, `gs://` or `az://` bucket, or a directory in the repo that a Pages site deploys |
   | `prefix` | none | where the files go in the bucket; `url` serves that prefix as its root |
   | `endpoint` | none | an S3-compatible store's address |
   | `namespaces` | none | a tag prefix (a path in the repo, such as `platform/`) to the namespace its modules go under; the longest prefix wins |
   | `system` | `generic` | the third part of each address |
   | `download` | `tarball` | what each version's download points at: a `.tar.gz` beside it, its git tag (`git-tags`, which `publish` must list), or its OCI artifact (`oci`, which `publish` must list; OpenTofu only) |

   A module's address is `<host>/<namespace>/<name>/<system>`, where the name is its directory's name: `modules/network` is `modules.example.com/acme/network/generic`.

2. Give the publish job write access to the bucket.

   ```bash
   npx terragucci init
   ```

   The publish job on GitHub and Forgejo maps the bucket's key secrets as a job that [keeps reports in a bucket](/terragucci/guides/keep-reports-in-a-bucket/) does: for S3 the pair `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, for Azure `AZURE_STORAGE_KEY`. GitLab passes it CI/CD variables of those names.

3. Serve the bucket over HTTPS at `url`: a CDN in front of it, or its own static website endpoint with a certificate. Every reader of the registry needs read access to it, and only the publish job writes it.

4. After the next module change merges, the publish job writes:

   | File | Holds |
   |---|---|
   | `.well-known/terraform.json` | service discovery: `{"modules.v1": "/v1/modules/"}` |
   | `v1/modules/<namespace>/<name>/<system>/versions` | every published version |
   | `v1/modules/<namespace>/<name>/<system>/<version>/download` | `{"location": ...}`, the tarball, git tag or OCI artifact |
   | `v1/modules/<namespace>/<name>/<system>/<version>/<name>-<version>.tar.gz` | the module, with `download: tarball` |
   | `v1/modules/<namespace>/<name>/<system>/<version>/release.json` | the commit and content digest the next publish compares against |

   A static server sends no `X-Terraform-Get` header, so the download answer is a JSON body with `location`, which both binaries read. A version is listed in `versions` only after the files it points at are written.

5. Pin a root to the registry and run `init`. `~> 1.0` resolves to the newest `1.x` the registry lists.

In a monorepo, each part's modules can go under a namespace of their own. Tags are `<path>/v<version>`, so the path prefix of a module is its tag prefix:

```yaml
registry:
  bucket: s3://acme-modules
  url: https://modules.example.com
  namespace: acme
  namespaces:
    platform/: platform
    data/: data
```

`platform/modules/network` is `modules.example.com/platform/network/generic`. Two modules at one address stop the publish and name both.

With `dir`, the publish job writes the files into that directory of its checkout, beside what is there. You deploy the directory to the Pages site and keep the earlier versions in it (from the site's branch, for example), since `versions` lists only what the directory holds.

A [rollout](/terragucci/guides/roll-out-a-module-version/) of `modules/network` moves the `version` of each call to its registry address. A call pinned by a constraint such as `~> 1.0` has no one version to move, and the rollout refuses it.

## Attest each release

With `modules.attest`, the publish job also signs each new release with a key you hold and records the version in the release ledger on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle), so a root's pin can be checked against all of it.

1. Make a cosign key pair, and commit the public half.

   ```bash
   cosign generate-key-pair
   git add cosign.pub
   ```

   Keep `cosign.key` out of the repo. Signing never writes to Sigstore's public transparency log.

2. Add two more secrets, the same way as the registry credentials in step 4.

   | Variable | Holds |
   |---|---|
   | `COSIGN_PRIVATE_KEY` | the contents of `cosign.key` |
   | `COSIGN_PASSWORD` | its password |

3. Turn it on, and write the pipeline again.

   ```yaml
   modules:
     path: modules/*
     publish: git-tags
     attest: true          # or attest: { key: keys/modules.pub }
   ```

   ```bash
   npx terragucci init
   ```

   The publish job now installs cosign, checked against its release checksums, before it publishes.

4. After a module change merges, check what was released.

   ```bash
   npx terragucci verify-release modules/service 0.2.0
   ```

   It reads the tag as it stands now and prints `verified` for each target, or `refused` and why.

terragucci runs each version through these phases from this config, with no file of your own:

| Phase | Does |
|---|---|
| Archive | takes the bytes the tag names: the module archive for a git tag, the manifest for an OCI tag |
| Sbom | writes SPDX 2.3 JSON from the module's HCL: each provider in `required_providers`, at its lock file's version when there is one, and each module it calls from another source |
| Sign | signs the bytes with cosign |
| Provenance | attests SLSA v1 provenance naming the commit and the run |
| SbomAttestation | attests the SBOM |
| Verify | checks all three against `cosign.pub`; a job given the wrong key stops here, before it writes anything |
| Record | makes the release record: the module's path, the digest of those bytes, the commit, the run and the actor |

| What | Where |
|---|---|
| The release record | a line of `modules/releases.jsonl` on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) |
| The bundles and the SBOM | `modules/attest/<digest>/` beside it |
| An OCI tag's signature and attestations | attached to its manifest |
| A git tag and its record | pushed together in one atomic push; an OCI tag is pushed only after its record |

A tag pushed by hand has no record that matches it, and neither does one moved after its release; `verify-release` refuses both. To go back to an earlier version, [roll out](/terragucci/guides/roll-out-a-module-version/) that version again.

## Require attested releases

With `modules.require: attested`, `tf-check` and `tf-plan` check each module pin a root makes before they plan it. A root pinning a release that does not verify fails. The check report and plan note name its module call and version and say why.

In a Terragrunt repo the pin is each unit's `terraform { source }`. `tf-check` runs `terragucci check-pins` over every unit, and `tf-plan` takes a refused unit out of its wave, so it fails without planning while the rest of the wave plans.

```yaml
modules:
  publish: git-tags
  attest: true
  require: attested
```

Only these sources are checked; a module from anywhere else, such as the public registry, is left alone:

| Source | Checked when | Key | Ledger |
|---|---|---|---|
| This repo's own modules | `modules.attest` is on: the repo's git URL for `git-tags`, each `oci://` target, and the host of `modules.registry` | `modules.attest.key` | `chant/lifecycle` on `origin` |
| A publisher in another repo | `modules.trusted` lists it | its `key` | its `ledger` |

```yaml
modules:
  require: attested
  trusted:
    - source: git::https://git.example.com/platform/modules.git
      key: keys/platform-modules.pub
      ledger: https://git.example.com/platform/modules.git
```

To trust a publisher, commit their `cosign.pub` at the path `key` names. For each pin of a checked source:

| Check | Refused when |
|---|---|
| The pin | it names no one release: a git `ref` that is not a tag, an `oci://` source with no tag or digest, a registry source whose `version` is a constraint |
| The record | the publisher's ledger has no record of the bytes the tag names now, from the tag's commit: a tag pushed by hand, moved, or never published |
| The signature, provenance and SBOM | any of them is missing or does not verify against the key |

| Job | Reads the setting and the keys from |
|---|---|
| `tf-plan` | the base branch, as it reads [the policy](/terragucci/reference/policy/#the-base-branch-decides), so a pull request cannot turn the check off or trust a key of its own |
| `tf-check` | the base branch when its checkout has it, else the checkout |

A registry source is checked where its registry says the version is: the tarball's bytes, or the git tag or OCI artifact its download points at, each checked as that kind of source is. Under `download: tarball` a release is signed and recorded in the ledger before `versions` lists it. The jobs read the registry over HTTPS, as `tofu init` does, so a private CA's certificate goes in `NODE_EXTRA_CA_CERTS`.

Tags and the ledger are fetched with the jobs' own git access; an `oci://` source is read with no login, or with `TERRAGUCCI_REGISTRY_USER` and `TERRAGUCCI_REGISTRY_PASSWORD` when the job has them.

## Next

- [Roll out a new module version](/terragucci/guides/roll-out-a-module-version/) moves your roots onto it.
- [Environment variables and credentials](/terragucci/reference/environment/)

---

# Turn on drift checks

Source: https://intentius.io/terragucci/guides/turn-on-drift-checks/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/turn-on-drift-checks/.
Add a `drift:` cron to terragucci.yml, run `npx terragucci config check --json`
and `npx terragucci init`, and open a pull request. Tell me the GitLab schedule
or token scope I must set.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

A scheduled `tf-drift` run that plans every root, and one issue that groups what drifted like a pull-request plan.

## Prerequisites

| You need | Why |
|---|---|
| The pipeline from [Get your first plan note](/terragucci/getting-started/) | `init` adds the drift job to it |
| A plan role that can read your cloud | drift plans use the same read-only role as pull requests |
| Terraform or OpenTofu roots, or Terragrunt units | the issue names roots, or units in a Terragrunt repo |
| A cron expression in UTC | forge schedulers read cron in UTC |

## Steps

1. Set a schedule in `terragucci.yml`. Pick an odd minute; forge schedulers are busiest on the hour.

   ```yaml
   drift: "17 4 * * *"
   ```

2. Check the file.

   ```bash
   npx terragucci config check
   ```

   ```text
   terragucci.yml: ok
   approval: ledger (the default)
   ```

   A bad value is listed as a problem, and the command exits 2.

3. Write the pipeline again and merge it.

   ```bash
   npx terragucci init
   ```

**GitHub**
       `init` adds a `drift` job with the cron. A `workflow_dispatch` with no `pr` input runs it by hand.
**GitLab**
       Set the same cron under CI/CD, Schedules. `GITLAB_TOKEN` (or the `token_env` variable) needs the `api` scope.

       Give the drift schedule no `TERRAGUCCI_SCHEDULE` variable. A schedule with `TERRAGUCCI_SCHEDULE` set to `comments` is the [comments schedule](/terragucci/guides/re-plan-from-a-comment/), and its pipelines run no drift job.
**Forgejo**
       The same job and trigger as GitHub.

4. Wait for the first run, or start one.

   `terragucci stage tf-drift` plans each root with `-refresh-only`, comparing state with real objects. Only an object changed or deleted outside Terraform counts as drift, and a merged but unapplied change does not. A [choudoufu](/terragucci/concepts/glossary/#choudoufu) root under live resource markers plans in full instead ([below](#live-roots)).

5. Read the issue.

   Each project has at most one open issue, `terragucci: drift found`, which every run updates. A root that cannot be refreshed fails the job; drift alone does not.

   | Event | The issue |
   |---|---|
   | Drift found | opened, or updated if one is open |
   | Every root clean | closed |
   | A root could not be planned | left as it is |

**GitHub**

**GitLab**

**Forgejo**

6. Remediate the drift.

   With `respond.drift` left at its default, the drift job also opens a pull request from `terragucci/drift`. It writes the live value where the root's own resource block sets a literal, and adds an import block for a resource the state does not hold. [Responses](/terragucci/reference/responses/#drift) lists what is only reported.

   | To | Do | Then |
   |---|---|---|
   | keep the live value | read the pull request, comment `/terragucci plan` on it for its plan note ([Re-plan from a comment](/terragucci/guides/re-plan-from-a-comment/)), and merge it | the apply job applies it in waves, behind the gate like any change |
   | put the object back | close the pull request and apply the root again | the apply makes the object match the code |

   A coding agent can take what the pull request cannot write (a value set through a variable or a module). Set [`agent.drift`](/terragucci/guides/agent-fix-drift/) and the drift issue starts an agent that returns its change as a pull request.

   Nothing in the drift job applies or merges. Each wave's approval and each run's report stay in the [audit trail](/terragucci/reference/audit-trail/).

   Under `respond.drift: attribute` the issue also names each attribute's changer from the audit log ([Drift attribution](/terragucci/reference/responses/#drift-attribution)):

7. Watch for an overdue note.

   When the schedule stops, the next pull request's plan note says why the drift checks are overdue ([Overdue drift checks](/terragucci/reference/stages/#overdue-drift-checks)).

## Roots another branch applies

With [`apply.branches`](/terragucci/reference/config/#apply-from-other-branches), the drift job checks a root that another branch applies against that branch's code. The job runs on the default branch and plans the root in a checkout of its branch fetched from `origin`. The log names the branch and its commit:

```text
apply.branches: envs/prod/app plans from release at 3f9a1c2e, the branch that applies it
```

A provider, backend or version the branch sets differently is the one the check uses, so a difference between the two branches is never reported as drift. A root whose branch cannot be fetched fails its check with the reason; it is never checked against the default branch instead. In a Terragrunt repo, a branch's units plan with one `run --all` in that branch's checkout.

## Live roots

A choudoufu root under live resource markers keeps no state to refresh: every plan of it reads the live system, and choudoufu refuses `-refresh-only` there. `tf-drift` plans such a root in full, and each change the plan would make is drift, read from the live side:

| The plan would | The issue says |
|---|---|
| change an attribute | the attribute changed |
| create a resource | it no longer exists |
| destroy a resource | it exists outside the code |

A change merged to the default branch but not applied yet also shows here, since the plan cannot tell it from a change made outside choudoufu. The rest of the drift job is the same: one issue, `respond.drift` and attribution.

## Next

- [Stages](/terragucci/reference/stages/) lists what `tf-drift` reads and writes.

---

# Keep reports in a bucket

Source: https://intentius.io/terragucci/guides/keep-reports-in-a-bucket/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/keep-reports-in-a-bucket/.
Add the `reports:` block for bucket <bucket>, rerun `npx terragucci init`, write
the access policy the page gives for my cloud as a file for me to review, and open a pull request.
Do not create the role, the bucket, the container, any secret or the front door stack.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

Every run's report in a bucket under one path per run, and an `index.html` that lists every plan you have run.

## Prerequisites

| Cloud | Store | Identity the plan job writes with |
|---|---|---|
| AWS | an S3 bucket, or an S3-compatible store such as R2 or MinIO | `reports.role` over OIDC, or keys |
| GCP | a Cloud Storage bucket, through its JSON API | the plan service account of `oidc.gcp` |
| Azure | a Blob Storage container | the plan client of `oidc.azure`, or the account key |

[OIDC](/terragucci/reference/pipeline/#credentials) sets up the GCP and Azure identities.

## Steps

1. Name the bucket in `terragucci.yml`.

**AWS**
   ```yaml
   reports:
     bucket: s3://acme-terragucci
     prefix: reports
     url: https://reports.acme.example
     role: arn:aws:iam::123456789012:role/terragucci-reports
   ```

   For a store that is not AWS, add `endpoint`; without it, the job reads `AWS_ENDPOINT_URL_S3` or `AWS_ENDPOINT_URL`.

   Requests are signed for `AWS_REGION` or `AWS_DEFAULT_REGION`, else `us-east-1`. To sign for another region, set it in the config's `env`:

   ```yaml
   env:
     AWS_REGION: eu-west-2
   ```
**GCP**
   ```yaml
   reports:
     bucket: gs://acme-terragucci
     prefix: reports
   ```

   `endpoint` defaults to `https://storage.googleapis.com`; an emulator sets its own.
**Azure**
   ```yaml
   reports:
     bucket: az://acmeterragucci/reports
     prefix: reports
   ```

   The bucket is `az://<storage account>/<container>`. Set `endpoint` for a sovereign cloud or an emulator; it defaults to `https://<account>.blob.core.windows.net`.

   `url` is where a browser opens the reports, such as the front door (step 5). The plan note links `report.html` and each root's `plan.txt` there. Without `url` the note uses presigned bucket links that last up to 7 days.

2. Regenerate the pipeline and commit it.

   ```bash
   npx terragucci init
   ```

3. <span id="3-give-the-job-an-identity-that-writes-only-reports"></span>Give the job an identity that writes only reports.

   The plan job runs the pull request's code, and that code can read its credentials. Limit this identity to read and write under the prefix.

**AWS**
   Allow only `s3:GetObject` and `s3:PutObject` on `arn:aws:s3:::acme-terragucci/reports/*`.

   With `oidc` set, `reports.role` is that identity, assumed through STS `AssumeRoleWithWebIdentity` under a trust policy like your plan role's. `config check` refuses a `reports.role` that is the plan or apply role.

   Without `oidc`, give an IAM user the same policy and store its keys as secrets. `init` passes them only to the jobs that plan, where OpenTofu sees them too.

   | Secret | Needed |
   |---|---|
   | `AWS_ACCESS_KEY_ID` | always |
   | `AWS_SECRET_ACCESS_KEY` | always |
   | `AWS_SESSION_TOKEN` | when the keys are temporary |

   | Order | Identity |
   |---|---|
   | 1 | `reports.role` |
   | 2 | `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` |
   | 3 | `AWS_ROLE_ARN`, which a job with `oidc` sets to its own role; that role then needs write access to the reports |

   A role is assumed with the token in `AWS_WEB_IDENTITY_TOKEN_FILE`; `AWS_ENDPOINT_URL_STS` or `AWS_ENDPOINT_URL` sets the STS address. When STS refuses it, the job fails with STS's error.
**GCP**
   Writes go through `oidc.gcp.plan_service_account`, using the `external_account` file in `GOOGLE_APPLICATION_CREDENTIALS`.

   | Grant to the plan service account | On | For |
   |---|---|---|
   | `roles/storage.objectUser`, with an IAM condition on the `reports/` prefix | the bucket | reading and writing reports |
   | `roles/iam.serviceAccountTokenCreator` | the service account itself | signing the estate page's link through IAM `signBlob` |

   A `service_account` key file in `GOOGLE_APPLICATION_CREDENTIALS` works too: requests carry a JWT it signs, and links are signed with the key.
**Azure**
   The job writes as `oidc.azure.plan_client_id`, trading its token in `ARM_OIDC_TOKEN_FILE_PATH` at Entra ID for a storage token.

   | Assign to the plan client | Scope | For |
   |---|---|---|
   | Storage Blob Data Contributor | the container | reading and writing reports |
   | Storage Blob Delegator | the storage account | the user delegation key that signs a link |

   `AZURE_AUTHORITY_HOST` names Entra ID outside the public cloud, such as `https://login.microsoftonline.us`. Without `oidc.azure`, store the account key as the secret `AZURE_STORAGE_KEY`; `init` maps it to the jobs that plan. An account key reaches every container in the account.

**GitHub**
   Store them as repository secrets.
**GitLab**
   Use unprotected CI/CD variables.
**Forgejo**
   Repository secrets, as on GitHub.

   Even so, a pull request's plan can overwrite any object under the prefix, including the index. The apply job's CI artifact is the record of what was applied.

4. Open a pull request. When the plan job finishes, its log says where the report went:

   ```text
   report: terragucci-report/report.html
   copied to the bucket under reports/github.com/acme/infra/2026/10/4f1a9c0d2e7b8a6c5d4e3f2a1b0c9d8e7f6a5b4c/tf-plan; index rewritten at reports/github.com/acme/infra/index.json and reports/index.json
   served at https://reports.acme.example/reports/github.com/acme/infra/2026/10/4f1a9c0d2e7b8a6c5d4e3f2a1b0c9d8e7f6a5b4c/tf-plan/report.html
   ```

   Each run gets one path holding the commit's full SHA. Links inside a report are relative:

   ```text
   reports/github.com/acme/infra/2026/10/4f1a9c0d2e7b8a6c5d4e3f2a1b0c9d8e7f6a5b4c/tf-plan/report.html
   reports/github.com/acme/infra/2026/10/4f1a9c0d2e7b8a6c5d4e3f2a1b0c9d8e7f6a5b4c/tf-apply-wave-2/report.json
   ```

   | Forge | Commit in the path |
   |---|---|
   | GitHub | `GITHUB_SHA`, the merge commit on a pull request |
   | GitLab | `CI_COMMIT_SHA` |
   | Forgejo | `GITHUB_SHA` |

5. <span id="5-serve-the-index"></span>Open the reports.

   Every upload adds the run's row to two `index.json` files, one at the project's path and one at the top of the prefix, and writes `index.html` from each. A `tf-apply` wave also writes these at the project's path:

   | File | Holds |
   |---|---|
   | `inventory.json` | the resources each applied root holds |
   | `changes.json` | what the wave did to each resource |
   | `states.json` | the version of each applied root's state |

   Writes are retried up to 8 times:

   | Store | Index write |
   |---|---|
   | S3, Azure Blob | conditional: `If-Match` the ETag read, or `If-None-Match: *` |
   | GCS | conditional: `ifGenerationMatch` the generation read, or `0` |
   | An S3-compatible store with no ETag | plain write, last run wins |
   | An S3-compatible store that answers `501 Not Implemented` | the condition is dropped |

   The bucket holds every plan, including each attribute value not marked sensitive. Keep it private and open it one of two ways:

   | | Presigned link | Front door |
   |---|---|---|
   | You deploy | nothing | one CloudFormation stack in your account, in `us-east-1`; AWS only |
   | Who can open it | anyone holding the link, until it expires | whoever your identity provider signs in |
   | What opens | one object; its links to other reports need links of their own | every report and index, with their links |
   | `reports.url` | not set: the plan note links `report.html` and each `plan.txt`, presigned | `https://<DomainName>` |

**Presigned link**
   Sign one object for an hour:

   | Cloud | Command | Longest life |
   |---|---|---|
   | AWS | `aws s3 presign s3://acme-terragucci/reports/github.com/acme/infra/index.html --expires-in 3600` | 7 days with an IAM user's keys; a role's session ends sooner |
   | GCP | `gcloud storage sign-url gs://acme-terragucci/reports/github.com/acme/infra/index.html --duration 1h --impersonate-service-account <service account>` | 7 days |
   | Azure | `az storage blob generate-sas --account-name acmeterragucci --container-name reports --name reports/github.com/acme/infra/index.html --permissions r --expiry <time> --auth-mode login --as-user --full-uri` | 7 days |

   [`terragucci estate`](/terragucci/guides/see-every-project/) prints such a link to its page on each cloud.
**Front door**
   Deploy the template in [The front door](#the-front-door) below and set `url` to its address:

   ```yaml
   reports:
     url: https://reports.acme.example
   ```

   A run that sent a trace also gets `traces/<trace id>.html` under the prefix, forwarding to its report. With `dashboards: true`, the Runs dashboard links it.

   [The reports bucket](/terragucci/reference/reports-bucket/) lists every key under the prefix and the JSON Schema of each object.

Retention is your bucket's lifecycle rule.

## The front door

The template puts CloudFront and an OpenID Connect sign-in with a signed session cookie in front of the bucket. It runs in your account and talks to nothing of terragucci's.

First register a web application with your identity provider. Give it the redirect URI `https://reports.acme.example/_terragucci/callback` and the `openid` and `email` scopes. Any provider whose token endpoint takes `client_secret_post` works; Google, Microsoft Entra ID and Okta do.

1. Store the client secret in Secrets Manager, in `us-east-1`:

   ```bash
   aws secretsmanager create-secret --region us-east-1 \
     --name terragucci-reports-client --secret-string '<client secret>'
   ```

2. Deploy the template:

   ```bash
   curl -fsSLO https://intentius.io/terragucci/reports-front-door.json
   aws cloudformation deploy --region us-east-1 --stack-name terragucci-reports \
     --template-file reports-front-door.json --capabilities CAPABILITY_IAM \
     --parameter-overrides ReportsBucket=acme-terragucci ReportsBucketRegion=us-east-1 \
   DomainName=reports.acme.example HostedZoneId=Z0123456789ABCDEFGHIJ \
   OidcIssuer=https://accounts.google.com OidcClientId=<client id> \
   OidcClientSecretName=terragucci-reports-client AllowedEmailDomain=acme.example
   ```

3. Let the distribution read the bucket by adding the statement in the stack's `BucketPolicyStatement` output to the bucket's policy:

   ```bash
   aws cloudformation describe-stacks --region us-east-1 --stack-name terragucci-reports \
     --query "Stacks[0].Outputs[?OutputKey=='BucketPolicyStatement'].OutputValue" --output text
   ```

   `WriteBucketPolicy=true` writes it instead for a bucket with no policy of its own. A bucket encrypted with your own KMS key also needs `kms:Decrypt` for `cloudfront.amazonaws.com` under the same `AWS:SourceArn` condition.

4. Set `url: https://reports.acme.example` under `reports:` and run `npx terragucci init` again.

| Parameter | Default | Meaning |
|---|---|---|
| `ReportsBucket` | required | `reports.bucket` without `s3://` |
| `ReportsBucketRegion` | `us-east-1` | the bucket's region |
| `DomainName` | required | the name people open |
| `HostedZoneId` | empty | the Route 53 zone of `DomainName`, for its A and AAAA alias records and the certificate's validation; empty writes no record |
| `CertificateArn` | empty | an ACM certificate in `us-east-1` for `DomainName`; empty requests one |
| `OidcIssuer` | required | such as `https://accounts.google.com` or `https://login.microsoftonline.com/<tenant>/v2.0` |
| `OidcClientId` | required | the web application's client id |
| `OidcClientSecretName` | required | the secret from step 1 |
| `AllowedEmailDomain` | empty | only verified addresses at this domain get in; empty admits anyone the issuer signs in |
| `SessionHours` | `12` | how long a sign-in lasts |
| `WriteBucketPolicy` | `false` | `true` writes the bucket policy |

| The stack makes | Named |
|---|---|
| CloudFront distribution, caching nothing, HTTPS only | `DistributionId` output |
| Origin Access Control, signing every request to the bucket | the stack name |
| Lambda@Edge function on every viewer request, and its role | the stack name |
| Secrets Manager secret with the settings and a generated session key | the stack name |
| ACM certificate, when `CertificateArn` is empty | its ARN |
| Route 53 A and AAAA alias records, when `HostedZoneId` is set | `DomainName` |

A request without a session cookie goes to the identity provider and then back to its report. `/_terragucci/logout` clears the session. A parameter change reaches the edge within five minutes.

Deleting the stack can fail on the function while CloudFront removes its copies, which takes a few hours; delete it again after that.

## Next

- [The plan report](/terragucci/reference/report/) shows what a report holds.
- [Report JSON schema](/terragucci/reference/report-schema/) is the format a script reads from the bucket.

---

# Send traces and metrics

Source: https://intentius.io/terragucci/guides/send-traces-and-metrics/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/send-traces-and-metrics/.
Add `OTEL_EXPORTER_OTLP_ENDPOINT` under `env:` in terragucci.yml, `telemetry.headers_secret` if the collector needs a key, and `dashboards: true`.
Run `npx terragucci config check --json` and `npx terragucci init`, and open a pull request with terragucci.yml, the pipeline and observability/terragucci/.
List the secret I must add for my forge; do not create it.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

Every plan, drift and apply job sends one trace and its metrics over OTLP to your collector, and your Grafana shows nine dashboards and the alerts `init` writes. Nothing else receives them.

With `binary: choudoufu` ([set it up](/terragucci/guides/use-a-binary/#choudoufu)), the traces and reports also carry provider-call timings, timings summed by resource type on a large estate, and state lock waits.

## Prerequisites

| You need | Why |
|---|---|
| The pipeline from [Get your first plan note](/terragucci/getting-started/) | `init` adds the variables to its jobs |
| An OpenTelemetry collector with an OTLP/HTTP receiver (port 4318) the runners can reach | the jobs send OTLP/JSON over HTTP, not gRPC |
| Prometheus, through the collector's Prometheus exporter or remote write | the metrics and the dashboards' queries |
| Grafana, and Tempo for traces | the dashboards; only the Runs dashboard's trace list needs Tempo |

An unreachable collector never fails a stage, so you can turn this on before the collector is ready.

## Steps

1. Point every job at the collector in `terragucci.yml`.

   ```yaml
   env:
     OTEL_EXPORTER_OTLP_ENDPOINT: https://otel-collector.example.com:4318
   ```

   Traces go to `/v1/traces` and metrics to `/v1/metrics` under it. `env` holds values only; a key goes in the next step. [Variables](/terragucci/reference/observability/#variables) lists the other OpenTelemetry variables the jobs read.

2. If the collector needs a key, name the secret that holds the headers.

   ```yaml
   telemetry:
     headers_secret: OTLP_HEADERS
   ```

   The generated plan, apply and drift jobs set `OTEL_EXPORTER_OTLP_HEADERS` from it. Its value is `key=value` pairs, such as `x-api-key=abc123`.

**GitHub**
       Add a repository secret named `OTLP_HEADERS` under Settings > Secrets and variables > Actions.
**GitLab**
       Under Settings > CI/CD > Variables, add `OTLP_HEADERS` as a masked variable.
**Forgejo**
       Create the secret `OTLP_HEADERS` in Settings > Actions > Secrets.

   A pull request from a fork gets no secrets.

3. Ask for the dashboards and alerts.

   ```yaml
   dashboards: true
   ```

   Grafana datasources not named `prometheus` and `tempo` need their uids here:

   ```yaml
   dashboards:
     prometheus: my-prometheus
     tempo: my-tempo
   ```

   [Dashboard settings](/terragucci/reference/observability/#dashboard-settings) lists the folder, path and alert thresholds.

4. Link each report to its trace (optional).

   ```yaml
   telemetry:
     headers_secret: OTLP_HEADERS
     trace_url: "https://grafana.example.com/explore?left=%7B%22datasource%22:%22tempo%22,%22queries%22:%5B%7B%22query%22:%22{trace_id}%22%7D%5D%7D"
   ```

   The report then links the run's trace instead of printing its id. The Runs and Estate dashboards link back to the reports when `reports.url` is set.

5. Check the file and write the pipeline again.

   ```bash
   npx terragucci config check
   npx terragucci init
   ```

   ```text
   terragucci.yml: ok
   approval: ledger (the default)
   ```

   `init` adds the variables to the jobs and writes `observability/terragucci/`:

   | File | Load it into |
   |---|---|
   | `grafana/dashboards/<uid>.json` | Grafana, at the dashboards `path` (default `/var/lib/grafana/dashboards/terragucci`) |
   | `grafana/provisioning/dashboards/terragucci.yaml` | Grafana, under `/etc/grafana/provisioning/dashboards/` |
   | `grafana/provisioning/alerting/terragucci.yaml` | Grafana, under `/etc/grafana/provisioning/alerting/` |
   | `prometheus/terragucci.rules.yml` | Prometheus, in `rule_files` |

   Page from the Grafana alerting file or from the Prometheus `ErrorBudgetBurn` alerts, not both. `init` leaves alone any file in that directory it did not write.

6. Add the span metrics connector to your collector, for the SLO dashboards:

   ```yaml
   connectors:
     spanmetrics:
       namespace: terragucci.spans
       dimensions:
         - name: terragucci.stage
         - name: terragucci.project
         - name: terragucci.result
       resource_metrics_key_attributes: [service.name, terragucci.project]
       histogram:
         unit: s
         explicit:
           buckets: [5s, 15s, 30s, 60s, 120s, 300s, 600s, 1200s, 1800s, 3600s]
   ```

7. Open and merge a pull request with `terragucci.yml`, the pipeline and `observability/terragucci/`.

8. Check the next pull request that changes a root. Its plan job sends a trace with a span per root and the binary's spans inside it, and the Pipeline health and Change review dashboards show the run.

## Dashboard requirements

| Dashboard | Fills in after |
|---|---|
| Pipeline health, Change review, Runs, Estate | a plan on a pull request |
| Estate's Delivery panels | the scheduled estate job with `OTEL_EXPORTER_OTLP_ENDPOINT` set ([See every project](/terragucci/guides/see-every-project/)) |
| Drift | a scheduled drift run ([Turn on drift checks](/terragucci/guides/turn-on-drift-checks/)) |
| Rollouts and waves | a wave on the default branch, or one that waits for an approval |
| The three SLO dashboards | the recording rules in Prometheus, and the span metrics connector |

## Next

- [Traces and metrics](/terragucci/reference/observability/) lists every span, metric, label and alert.
- [Keep reports in a bucket](/terragucci/guides/keep-reports-in-a-bucket/) gives the dashboards' report links somewhere to go.

---

# Govern many repos from one place

Source: https://intentius.io/terragucci/guides/govern-many-repos/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/govern-many-repos/.
In this control repo, write terragucci.yml with the projects I name, run `npx terragucci config check`, then run the preview, `npx terragucci reconcile --config terragucci.yml`, and show me its output for each project.
Open a pull request in this control repo with the file. Print the `--mode apply` command for me to run; do not run it.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

A [control repo](/terragucci/concepts/control-repo/) whose `terragucci.yml` lists every project. One command previews each project's pipeline and another opens a pull request in each project that changes; the projects' own pipelines apply.

## Prerequisites

| You need | Why |
|---|---|
| A repo to act as the control repo | it holds only `terragucci.yml` |
| A token per forge that can push branches and open pull requests: `GITHUB_TOKEN`, `GITLAB_TOKEN` or `FORGEJO_TOKEN`, or the variable a project's `token_env` names | `reconcile` opens a pull request in each project |
| Projects on GitHub, GitLab or Forgejo | they can be mixed in one file |

## Steps

1. List the projects.

   A project is its address on the forge. `defaults` apply to every project, and a project's own keys override them.

   ```yaml
   defaults:
     binary: tofu
     gate: on-destructive
   projects:
     github.com/acme/infra:
       roots: ["envs/*/*"]
     gitlab.example.com/platform/network:
       binary: terraform
       drift: "17 4 * * *"
     codeberg.org/acme/edge: {}
   ```

   A repo you leave out is never touched. [terragucci.yml keys](/terragucci/reference/config/#keys) lists what a project can set.

   To check every project against one policy repo, put [`policy.source`](/terragucci/reference/policy/#a-shared-policy-source) under `defaults`:

   ```yaml
   defaults:
     policy:
       source: git+https://github.com/acme/policy.git@v3
   ```

   [Control repo](/terragucci/concepts/control-repo/#reconcile) lists what each project's pull request carries and what the project keeps.

2. Check the file.

   ```bash
   npx terragucci config check
   ```

   ```text
   terragucci.yml: ok
   approval: ledger (the default)
   ```

3. Preview.

   ```bash
   npx terragucci reconcile --config terragucci.yml
   ```

   This dry run says per project whether the pipeline would change, and prints the files and setup tips. `--project github.com/acme/infra` narrows it to one project; `--json` prints one object ([JSON output](/terragucci/reference/cli-json/#reconcile)).

4. Open the pull requests.

   ```bash
   npx terragucci reconcile --config terragucci.yml --mode apply
   ```

   Each project gets a pull request instead of a push to its main branch, and current projects are left alone; `--mode apply` runs no `terraform apply`. The exit code is 1 when any project failed.

5. Merge in each project.

   Each team reviews its pull request. A later `reconcile`, such as after editing `defaults`, opens one only where something changed.

## Next

- [Roll out a new module version](/terragucci/guides/roll-out-a-module-version/) works across projects.
- [Manage the control repo with Terraform](/terragucci/guides/manage-the-control-repo-with-terraform/) writes `terragucci.yml` with a provider, so a plan shows each change.
- [Environment variables and credentials](/terragucci/reference/environment/) lists the tokens.

---

# Choose choudoufu, Terraform, OpenTofu or Terragrunt

Source: https://intentius.io/terragucci/guides/use-a-binary/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/use-a-binary/.
Run `npx terragucci init --dry-run --json` and tell me which binary it picked and why.
Set `binary:` in terragucci.yml only if that pick is wrong, run `npx terragucci init`, and open a pull request.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Binary features

Every binary runs the same four stages: `tf-check`, `tf-plan`, `tf-apply` and `tf-drift`. choudoufu, the OpenTofu fork from the team behind terragucci, adds [twelve features](#choudoufu) on top of OpenTofu's.

| | choudoufu | Terraform | OpenTofu | Terragrunt |
|---|---|---|---|---|
| State | one record per resource in an S3 backend, and a tag on each resource; the state file is a cache | your backend | your backend | each unit's backend |
| What `tf-check` runs | `fmt -check`, `validate`, [`live-check`](/terragucci/reference/stages/#check) | `fmt -check`, `validate` | `fmt -check`, `validate` | `hcl fmt --check`, `hcl validate` |
| What the report times | each resource; [slow provider calls](/terragucci/reference/observability/#report-contents), [summed timings](/terragucci/reference/observability/#report-contents) on a large estate and [lock waits](/terragucci/reference/observability/#state-lock-waits) on a locking backend | per-resource timings: not reported (Terraform sends no traces) | each resource | each unit, from Terragrunt's run report |
| CI image | `terragucci-choudoufu`, choudoufu 0.25.0 | `terragucci-terraform`, Terraform 1.14.9 | `terragucci-tofu`, OpenTofu 1.13.1 | `terragucci-terragrunt`, Terragrunt 1.1.6 and OpenTofu 1.13.1 |
| Version pin | `version` only | `version`, `.terraform-version`, or an exact `required_version`; per root too | `version`, `.opentofu-version`, or an exact `required_version`; per root too | `terragrunt.version`, or an exact `terragrunt_version_constraint`; per unit too, with the binary's pins |

A pin the image does not carry is installed in the job and checked against the release's SHA256SUMS. Images are pinned by digest.

### A version per root

A root pinned by its own `.opentofu-version`, `.terraform-version` or exact `required_version` runs that version; the rest of its wave runs the job's. `version` in `terragucci.yml` can also be a map of root glob to version:

```yaml
binary: tofu
version:
  "envs/legacy/*": "1.9.1"
```

The plan and apply jobs install each pinned version once and run each root with its own. The plan note and the report name each root's binary and version:

```text
Binaries: tofu 1.10.6 for `old` (.opentofu-version); tofu 1.13.1 for 1 root.
```

Run `npx terragucci init` after adding a pin, so the check job validates each root with its version too. [A version per root](/terragucci/reference/config/#a-version-per-root) gives the order pins are read in.

## Your binary in `terragucci.yml`

**choudoufu**

```yaml
binary: choudoufu
```

On [choudoufu](https://github.com/INTENTIUS/choudoufu), the stages add:

| You get | Where you see it |
|---|---|
| A live check in `tf-check` on every push, before the apply waves, with no cloud credentials | [the `tf-check` log and check report](/terragucci/reference/stages/#check) |
| One record per resource in an S3 backend, each write conditional, with no lock table or database to run. The state file is a cache: never the record of what you own, and losing it costs a refresh | [Record writes](/terragucci/concepts/locking-and-staleness/#record-writes) |
| Each address finds its real resource: the apply writes a tag on each resource and the next plan reads it back | [Live resource markers](/terragucci/concepts/locking-and-staleness/#live-resource-markers) |
| How long a wave waited for a state lock, and how many tries it took, on a backend that locks | [the report, the trace and a metric](/terragucci/reference/observability/#state-lock-waits) |
| Which provider calls were slow, and the resource each was for | [the report's provider calls](/terragucci/reference/observability/#report-contents) |
| Reports that stay readable past a span budget on a large estate, with timings summed by resource type | [the report's summed timings](/terragucci/reference/observability/#report-contents) |
| Two applies of one estate that change different resources run at the same time; one that changes a resource another is applying waits for it, or, from a comment, is refused, before it reaches the cloud. A killed apply leaves nothing to release, and the next one refuses a plan it made stale | [Locking with choudoufu](/terragucci/concepts/locking-and-staleness/#with-choudoufu) |
| A role scoped to one estate by its ownership tag: it applies that estate and is refused on another estate's resources | [your cloud's IAM](/terragucci/concepts/locking-and-staleness/#live-resource-markers) |
| One record store bucket for every estate, each under its own prefix | [your bucket](/terragucci/concepts/locking-and-staleness/#one-backend-for-all-your-estates) |
| A resource moved to another estate by rewriting its tags, or a state adopted into an estate, through a migration approved by digest | [Estates](/terragucci/guides/move-resources-between-roots/#estates) |
| A root that reads another estate's outputs through `data "terraform_estate_outputs"` applies after the root whose `live` block owns that estate | the layers `init --dry-run` counts, and each wave's apply order |
| Drift checks on roots under live resource markers: each plan reads the live system, so `tf-drift` plans the root in full and reports what the plan would change back as drift | [the drift issue](/terragucci/guides/turn-on-drift-checks/#live-roots) |

`init` never picks choudoufu on its own: set `binary: choudoufu` or run `npx terragucci init --binary choudoufu`.

A `live-check` refusal fails `tf-check` and names its rule in the log. terragucci does not read a root's `required_version` as a choudoufu release.
**Terraform**

```yaml
binary: terraform
```

A `.terraform-version` file makes `init` pick it; the table in step 1 below has the full order.

**OpenTofu**

```yaml
binary: tofu
```

`init` picks it for a `.opentofu-version` file or `.tofu` files, and when nothing points elsewhere.

**Terragrunt**

```yaml
binary: tofu   # or terraform: the tool Terragrunt calls
```

A `root.hcl` or `terragrunt.hcl` turns on Terragrunt, and each unit is a root. Under Terragrunt, `binary` is `tofu`, `terraform` or `choudoufu`, which Terragrunt calls through `TG_TF_PATH`. Terraform is installed in the job; with `choudoufu` the jobs run in the choudoufu image and install Terragrunt. [Use Terragrunt](/terragucci/guides/use-terragrunt/) has the rest.

## Steps

1. See what `init` picked. The first line names the binary and why.

   ```bash
   npx terragucci init --dry-run
   ```

   ```text
   found 15 roots in 2 layers, tofu 1.13.1 (tofu on the path), forge github (the origin remote (github.com))
   ```

   `binary:` in `terragucci.yml` comes first, then `--binary`, then:

   | Order | Source | Binary |
   |---|---|---|
   | 1 | `.opentofu-version` | `tofu` |
   | 2 | `.terraform-version` | `terraform` |
   | 3 | `.tofu` files in a root | `tofu` |
   | 4 | `tofu` on the path | `tofu` |
   | 5 | `terraform` on the path | `terraform` |
   | 6 | nothing found | `tofu` |

   If it picked the one you want, stop here.

2. Put your tab's `binary:` line in `terragucci.yml`, or run `npx terragucci init --binary <name>`.

3. Write the pipeline again and commit it.

   ```bash
   npx terragucci init
   ```

   ```text
   found 15 roots in 2 layers, tofu 1.13.1 (terragucci.yml), forge github (the origin remote (github.com))
   updated .github/workflows/terragucci.yml
   using terragucci.yml
   ```

## Next

- [Use Terragrunt](/terragucci/guides/use-terragrunt/) if your roots are Terragrunt units.
- [Stages](/terragucci/reference/stages/) lists the inputs, permissions and outputs of each stage.

---

# Use Terragrunt

Source: https://intentius.io/terragucci/guides/use-terragrunt/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/use-terragrunt/.
Run `npx terragucci init --dry-run --json`, list the units and waves it found,
add a `terragrunt:` block only where the page says one is needed, and open a
pull request.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

A pipeline that checks with `terragrunt hcl fmt` and `hcl validate` and plans the units a pull request reaches. It applies a wave at a time behind the same gate as plain roots.

## Prerequisites

| You need | Why |
|---|---|
| A Terragrunt repo with a `root.hcl`, `terragrunt.hcl` or `terragrunt.stack.hcl` | `init` detects Terragrunt from it |
| Terragrunt 1.1 or later | the oldest version terragucci supports |
| terragucci installed ([Get your first plan note](/terragucci/getting-started/)) | `init` writes the pipeline |

## Steps

1. Run init.

   ```bash
   npx terragucci init --dry-run
   ```

   Each unit `terragrunt find` lists is a root, so `.terragrunt-filters` is honoured. `roots` does not apply here, and `init` refuses it: leave units out with `terragrunt.exclude`. The units of an explicit stack are found too ([Explicit stacks](#explicit-stacks)).

   When Terragrunt is not on the path, `init` cuts the waves from the units' `dependency` and `dependencies` paths, and the apply jobs check them with `terragrunt find`.

2. Name the tool Terragrunt runs underneath with `binary`: `tofu`, `terraform` or [`choudoufu`](/terragucci/concepts/glossary/#choudoufu).

   ```yaml
   binary: tofu
   ```

   With `choudoufu` the jobs run in the choudoufu image and install Terragrunt beside it.

3. Tune it if you need to. A `terragrunt:` block sets the version, parallelism, roles by unit path, excluded units and how dependents are planned ([terragucci.yml keys](/terragucci/reference/config/#the-terragrunt-block)).

   ```yaml
   terragrunt:
     exclude: ["live/sandbox/**"]
     dependents: follow
   ```

4. Write the pipeline.

   ```bash
   npx terragucci init
   ```

   Commit the pipeline, and under `approval: sealed` [`chant.workspace.json`](/terragucci/concepts/glossary/#chantworkspacejson), and open a pull request. Under `sealed`, set up the signers file before the first wave waits, as [Approve a waiting wave](/terragucci/guides/approve-a-wave/) describes.

## Differences

| What | How |
|---|---|
| Which units a change reaches | Terragrunt's own change detection, plus files a module reads with `file()`, modules called from inside modules, and stack templates |
| Units that depend on a changed unit | a later wave than the unit they read from |
| `mock_outputs` | a unit whose plan would read mock values waits for its upstream to apply, so no approval covers a made-up value. In a pull request it plans on its upstream's planned outputs instead, when they are known ([below](#later-layers)) |
| Each wave | one dependency layer, canary layers first, in its own apply job. One `terragrunt run --all` saves the plans and a second applies them. The last job also runs any layer added since `init` |
| The gate | as for plain roots, one gate per wave; the set digest covers the units whose plan changes a resource or an output |
| Credentials | a plan role and an apply role chosen by the unit's path; a unit that sets its own `iam_role` keeps it |
| `/terragucci apply` | on a merged pull request (GitHub, Forgejo, and GitLab with `comments:` set) reruns its waves from the merge commit behind the same gate, with [these refusals](/terragucci/guides/re-plan-from-a-comment/#apply-a-merged-pull-request); it approves nothing |
| When a change applies | after it merges, by default. With `apply.when: pull-request` (GitHub, Forgejo, and GitLab with `comments:` set), `/terragucci apply` on the approved open pull request applies its waves of units from the head: [Apply a pull request before it merges](/terragucci/guides/apply-before-merge/) |
| Applying from other branches | [`apply.branches`](/terragucci/reference/config/#apply-from-other-branches) maps a branch to unit globs: a push to it applies those units alone, in their own layer waves behind the gate, and the default branch leaves them alone |
| Locks before merge | on units: a changed unit and the units whose `dependency` blocks name it; a change outside every unit's directory locks every unit ([Locks](/terragucci/guides/apply-before-merge/#locks)) |
| `cost` | each unit's saved plan is priced, and `approve_above` holds a wave as it holds a wave of roots ([Estimate the cost of a change](/terragucci/guides/estimate-cost/)) |
| `steps` | each moment runs once around the wave's `run --all`, in every unit the step's `roots` globs match; `after: init` is refused, since Terragrunt inits each unit inside the plan ([Run steps around a stage](/terragucci/guides/run-steps/#in-a-terragrunt-repo)) |
| `waves.jobs` | a wide wave's job plans every unit and decides the gate; each share job plans and applies its own units with `run --all --filter` ([A wide wave across jobs](/terragucci/concepts/waves-and-approvals/#a-wide-wave-across-jobs)) |
| Dependency graph and blast radius | each unit, its wave and its `dependency` edges are in the run view and on the [estate page's graph](/terragucci/guides/see-every-project/); the plan note's blast radius lists the units that depend on a changed unit ([Blast radius in the plan note](/terragucci/concepts/waves-and-approvals/#blast-radius-in-the-plan-note)) |
| State versions | each unit's state version is recorded after its wave applies, its backend read from the unit's `remote_state` block ([Find the state version an apply left](/terragucci/guides/find-a-state-version/)) |
| A failed format check on a branch | the `fmt` job runs `terragrunt hcl fmt` and the binary's `fmt`, and pushes the commit to the branch |
| Drift | the drift job reports drift by unit; its pull request writes a drifted value into the unit's own `inputs` in `terragrunt.hcl` where its module reads that variable, and `respond.drift: attribute` names who changed it ([Drift](/terragucci/reference/responses/#drift)) |
| Generated backend and provider files | [`generate`](/terragucci/guides/generate-root-files/#in-a-terragrunt-repo) writes `terragucci.hcl` at the repo's root, whose `remote_state` and `generate` blocks give each unit that includes it its backend, providers and versions, and the check job holds it to `terragucci.yml` |
| Exporting a state version | `terragucci state export <unit>` prepares the unit through Terragrunt and exports a version of the state its `remote_state` block names, behind the same approval ([Export a state version](/terragucci/guides/export-a-state-version/)) |
| Moving resources between units | a migration file names units as it names roots; Terragrunt prepares each unit, and the move goes through the same gate ([Move resources between roots](/terragucci/guides/move-resources-between-roots/)) |
| A version per unit | a unit's `.opentofu-version` or `.terraform-version`, a `version` map glob, or an exact `terragrunt_version_constraint` in its own `terragrunt.hcl` picks its releases; each is installed in the job, and a wave runs as one `run --all` per pair of releases ([A version per root](/terragucci/reference/config/#a-version-per-root)) |

A held wave of units waits as a wave of roots does. It names its units and set digest and prints the approve command:

## Explicit stacks

The units a `terragrunt.stack.hcl` generates go through every stage as units the repo holds do. Each job runs `terragrunt stack generate` before it reads them, so keep `.terragrunt-stack/` in `.gitignore`.

```hcl
# live/stk/terragrunt.stack.hcl
unit "base" {
  source = "${get_repo_root()}/catalog/units/base"
  path   = "base"
  values = { rev = "1" }
}

unit "top" {
  source = "${get_repo_root()}/catalog/units/top"   # its dependency block reads ../base
  path   = "top"
}
```

`init` finds `live/stk/.terragrunt-stack/base` in wave 1 and `live/stk/.terragrunt-stack/top` in wave 2.

| Stage | With an explicit stack |
|---|---|
| `init` and every job | runs `terragrunt stack generate` first, so Terragrunt 1.1 or later must be on the path; without it `init` stops with an error naming the stack file |
| Check | generates the units, then `terragrunt hcl validate --inputs` checks them, so a unit whose template reads a value the stack file does not set fails the check, naming the generated unit |
| Which units a change reaches | a changed value in the stack file plans the unit it feeds; a changed unit template plans the units generated from it; their dependents wait as usual |
| Plan note and report | the note lists each stack file and the units it generates; `roots[].terragrunt.stack` is the stack's directory and `stack_file` its `terragrunt.stack.hcl` |
| Drift | generates the units in a fresh checkout and reports drift by generated unit. The drift pull request leaves a generated unit's drift in the issue, naming its stack file, since that unit's `terragrunt.hcl` is not in the repo |
| [`generate`](/terragucci/guides/generate-root-files/#in-a-terragrunt-repo) | keys `terragucci.hcl` by the paths the stack file's `unit` blocks generate, and requires each unit template in the repo to include it. A `stack` block (a nested stack) stops `generate` with an error, since only Terragrunt can list its units |
| Ephemeral copies, `state export`, migrations | generate the stack before they prepare a generated unit |
| Locks before merge | a change to a stack file or a template is outside every unit's directory, so it locks every unit |

## Layer-by-layer apply

terragucci applies a change one dependency layer at a time, and every layer applies only the plans a person approved.

1. The layer's wave plans its units with one `terragrunt run --all`, saving each unit's plan. Units of later layers are not planned for real yet; the pull request only previewed them.
2. Next comes the set digest over the saved plans that change a resource or an output, and the gate holds the wave until an approval of that digest.
3. A second `run --all` applies exactly those saved plans. Nothing is planned again between the approval and the apply.
4. The next layer's wave then plans against the state the layer before it left, and waits at its own gate. Its approval covers that real plan, not the preview made before its upstream applied.

| What you might expect from `run --all apply` | What a terragucci wave does |
|---|---|
| every unit applies at once | one dependency layer per wave, each behind its own gate |
| a plan made at apply time | the saved plans the approval names, applied as they were |
| a downstream unit planned against values its upstream has not produced yet | planned against the state its upstream left; a plan that would read `mock_outputs` fails its wave |

## Later layers

A pull request's plan covers the units of every layer the change reaches. When a unit's `dependency` block reads a unit planned in an earlier layer of the same plan, it is planned on that plan's outputs instead of the upstream's last applied ones. terragucci gives Terragrunt those values as the answer to the binary's `output -json` for the upstream, so Terragrunt itself evaluates the unit's `dependency` blocks, includes and inputs.

| A unit that reads | In the pull request's plan |
|---|---|
| outputs its upstream's plan knows | planned on those values; the note lists it under the units planned on another's planned outputs, and the report's `roots[].reads` says `planned` |
| an output its upstream knows only once it applies | not planned. The note names the output and the wave that settles it: ``reads `out` of live/app, unknown until wave 2 applies``. Its wave plans again once that wave applied, and the note gives no digest for it |
| an upstream that has no plan in this run: it failed, or waits for its own upstream | not planned, and the note says which upstream |
| an upstream whose plan changes no output, or that the change does not reach | planned on the upstream's applied outputs, which stand |

No unit is planned on a placeholder for an unknown value or on `mock_outputs`. A unit that reads its upstream without asking the binary (as Terragrunt does with `TG_DEPENDENCY_FETCH_OUTPUT_FROM_STATE`) gets no preview; the note says so.

With a base branch the plan also previews, layer by layer, the dependents of the units the change reaches; these provisional plans are outside every digest. Under `dependents: follow` the dependents are only listed, as planned once what they wait for applies.

After the merge each wave plans again on the state the earlier waves left, and its gate binds that plan. When a unit's plan differs from the preview in the merged pull request's plan note, the wave names each resource and attribute that moved before it prints its approve command:

```text
wave 2 of 3: pull request 12 previewed live/app on the planned outputs of the waves before; this unit plans differently now:
wave 2 of 3:   live/app: terraform_data.this (update): input differs from the preview
```

The wave's report keeps the comparison in `waves[].preview`, and its note shows it.

## Terragrunt Scale

`import terragrunt-scale` reads Gruntwork Pipelines' `.gruntwork/*.hcl` and each unit's `gruntwork.hcl`, and writes each environment's roles as [`terragrunt.credentials`](/terragucci/reference/config/#the-terragrunt-block).

```bash
npx terragucci import terragrunt-scale
```

```hcl
# .gruntwork/environments.hcl
environment "prod" {
  filter {
    paths = ["live/prod/*"]
  }
  authentication {
    aws_oidc {
      account_id         = aws.accounts.all.prod.id
      plan_iam_role_arn  = "arn:aws:iam::${aws.accounts.all.prod.id}:role/pipelines-plan"
      apply_iam_role_arn = "arn:aws:iam::${aws.accounts.all.prod.id}:role/pipelines-apply"
    }
  }
}
```

becomes, with `prod`'s id from `accounts.yml`:

```yaml
terragrunt:
  credentials:
    "live/prod/**":
      plan: arn:aws:iam::222222222222:role/pipelines-plan
      apply: arn:aws:iam::222222222222:role/pipelines-apply
```

A role built with a function is listed as not mapped. A filter path that matches no unit is named. The legacy `.gruntwork/config.yml` names no roles, so the import refuses it.

| Setting | Terragrunt Scale | terragucci |
|---|---|---|
| Roles | an `environment`'s `filter.paths` and `aws_oidc` roles; a unit's `gruntwork.hcl` | `terragrunt.credentials`: each path and the units below it, mapped to its plan and apply role; a unit's own roles come first, by its path |
| Accounts | `aws.accounts` and its `accounts.yml` | read for the account ids the role ARNs name |
| No authentication | `authentication {}` | no key: a unit no glob matches runs with the runner's credentials |
| Other clouds | `azure_oidc`, `gcp_oidc`, `custom` | none by unit path: `oidc.azure` or `oidc.gcp` sets one pair for every unit |
| Binary | `repository.tf_binary` | `binary` |
| Other settings | `repository`, `annotation` | not mapped: set `env`, `steps` or `terragrunt.exclude` by hand |

## Next

- [The same shop on Terragrunt](/terragucci/tutorial/terragrunt/) runs this on an example.
- [The generated pipeline](/terragucci/reference/pipeline/#terragrunt) shows how roles follow unit paths.

---

# Have an agent summarize a refused wave

Source: https://intentius.io/terragucci/guides/agent-refused-wave/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/agent-refused-wave/.
Add the explain-refusal job for wave <k> to the own-jobs file the guide's tab
for this forge names, set own_jobs in terragucci.yml to that file, run
`npx terragucci init`, give the job no permission beyond what that tab gives,
and open a pull request.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

One of four features that run a model; the others are the [`/terragucci agent` comment](/terragucci/guides/agent-change-a-pull-request/), the [drift agent](/terragucci/guides/agent-fix-drift/) and the [pull request review](/terragucci/guides/agent-review-a-pull-request/). It is off until you add its job by hand; every other feature runs without an agent ([what needs an agent](/terragucci/#opt-in-coding-agent)).

## Result

One comment on what changed between the approved plan and the refused one. The agent never approves, applies or merges, and its prompt forbids running terragucci.

## Prerequisites

| You need | Why |
|---|---|
| [Fix a refused wave](/terragucci/guides/fix-a-refused-wave/) done once by hand | the agent reads the same diff you print there |
| An API key for the model | the job runs Claude Code |
| On GitHub, a forge token that can comment but not push, approve or merge | the action posts the summary as a comment; on GitLab and Forgejo the summary is in the job's log and the job needs no token |
| The refused wave's artifact, `terragucci-report-apply-wave-<k>` | it holds the approved report and the refused one |

## Steps

1. Produce the diff, the agent's input, without a model:

   ```bash
   npx terragucci respond wave-refused --approved terragucci-report/approved --current terragucci-report/current --wave 2 --json
   ```

   The envelope lists each root whose plan digest moved and what moved inside it.

2. Add the job to a file of your own jobs, and name the file in `terragucci.yml`. Each time `init` rewrites its pipeline file, it writes every job the file holds after its own, unchanged. `reconcile` does the same in each project of a [control repo](/terragucci/concepts/control-repo/).

   ```yaml
   # terragucci.yml
   own_jobs: ci/own-jobs.yml
   ```

   | What | Value |
   |---|---|
   | Runs | when a wave's apply job fails on a refusal |
   | Wave jobs | `apply-wave-<k>`; with [`waves.jobs`](/terragucci/concepts/waves-and-approvals/#a-wide-wave-across-jobs), the wave's deciding job is `apply-wave-<k>` and a refused share keeps no approved report |
   | Input | the artifact `terragucci-report-apply-wave-<k>`, holding `approved/report.json` and `current/report.json` when refused |
   | Wave in the examples | 2; change the number everywhere for another |
   | Claude Code | pinned to 2.1.290, the release the [agent comment](/terragucci/guides/agent-change-a-pull-request/) job runs |

**GitHub**
       `ci/own-jobs.yml`. The job runs in the `terragucci` workflow after the wave's job, only when that job failed, and reads that run's artifact. A bare `failure()` would also run it on a branch push whose check failed, where the wave never ran.

       ```yaml
       explain-refusal:
         needs: apply-wave-2
         if: failure() && needs.apply-wave-2.result == 'failure'
         runs-on: ubuntu-latest
         permissions:
           contents: read
           pull-requests: write
           issues: write
         steps:
           - uses: actions/checkout@v4
           - uses: actions/download-artifact@v4
             continue-on-error: true
             with: { name: terragucci-report-apply-wave-2, path: reports }
           - run: >
               test -d reports/approved || exit 0;
               npx -y @intentius/terragucci respond wave-refused
               --approved reports/approved --current reports/current --wave 2
               --json > refusal.json
           - if: hashFiles('refusal.json') != ''
             uses: anthropics/claude-code-action@v1
             with:
               anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
               github_token: ${{ secrets.AGENT_FORGE_TOKEN }}
               prompt: |
                 Read refusal.json. Summarize which roots changed since the approval and why
                 the plan moved, in five lines or fewer. Do not run
                 terragucci or any apply command.
       ```
**GitLab**
       `ci/own-jobs.yml`. `init` writes the job into `.gitlab/terragucci.yml`, which your `.gitlab-ci.yml` includes. After the wave's job fails, it finds the artifact unpacked at `terragucci-report/`. Sharing the apply jobs' rule keeps it out of a branch's pipeline, which has no `apply-wave-2`, and `on_failure` with `needs` runs it only when `apply-wave-2` failed. A wave that failed for another reason leaves no approved report, and the job stops there. Give it `ANTHROPIC_API_KEY` as a masked variable. The summary stays in the job log; nothing is posted.

       ```yaml
       explain-refusal:
         stage: apply
         needs: [apply-wave-2]
         rules:
           - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CI_PIPELINE_SOURCE != "schedule"
             when: on_failure
         image: node:24
         script:
           - test -d terragucci-report/approved || exit 0
           - >
             npx -y @intentius/terragucci respond wave-refused
             --approved terragucci-report/approved --current terragucci-report/current --wave 2
             --json > refusal.json
           - >
             npx -y @anthropic-ai/claude-code@2.1.290 -p
             "Read refusal.json. Summarize which roots changed since the approval and why
             the plan moved, in five lines or fewer. Do not run
             terragucci or any apply command."
       ```
**Forgejo**
       `ci/own-jobs.yml`. Forgejo's runner takes `actions/download-artifact@v3`, which reads only its own run's artifacts, so the job runs in the `terragucci` workflow beside the wave's job, only when that job failed. `anthropics/claude-code-action` is a GitHub app, so the job runs the CLI and the summary stays in its log. The key is a repository secret; the job needs no write token.

       ```yaml
       explain-refusal:
         needs: apply-wave-2
         if: failure() && needs.apply-wave-2.result == 'failure'
         runs-on: docker
         container: node:24
         steps:
           - uses: actions/checkout@v4
           - uses: actions/download-artifact@v3
             with: { name: terragucci-report-apply-wave-2, path: reports }
           - run: >
               test -d reports/approved || exit 0;
               npx -y @intentius/terragucci respond wave-refused
               --approved reports/approved --current reports/current --wave 2
               --json > refusal.json
           - run: >
               test -f refusal.json || exit 0;
               npx -y @anthropic-ai/claude-code@2.1.290 -p
               "Read refusal.json. Summarize which roots changed since the approval and why
               the plan moved, in five lines or fewer. Do not run
               terragucci or any apply command."
             env:
               ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
       ```

   Then run `npx terragucci init` and commit the pipeline with the file. A job name `init` already gives one of its own jobs is refused.

3. Read the summary and choose between approving the new plan and reverting the change. The choice and the approval ([`terragucci approve`](/terragucci/reference/cli/#approve)) are yours.

## MCP or `--json`

| Where the agent runs | What it uses |
|---|---|
| in the explain-refusal job | `respond wave-refused --json` from the shell, on the wave's artifact: the job has the two reports and no bucket credentials |
| at your desk | [`terragucci mcp`](/terragucci/guides/agent-read-over-mcp/): `run_view` for where each wave of the commit stands, `report` for the refused wave's report, and `waiting` for each wave that waits for an approval, with the command a person runs to approve it |

## Next

- [Approve a waiting wave](/terragucci/guides/approve-a-wave/)
- [Waves and approvals](/terragucci/concepts/waves-and-approvals/)

---

# Have an agent change a pull request

Source: https://intentius.io/terragucci/guides/agent-change-a-pull-request/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/agent-change-a-pull-request/.
Add the `agent.comment` block to terragucci.yml, run `npx terragucci config check` and `npx terragucci init`, and open a pull request with the result.
List the machine user, token scopes, secrets and ruleset I must set; do not create tokens or secrets yourself.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

One of four features that run a model; the others are [summarizing a refused wave](/terragucci/guides/agent-refused-wave/), [fixing drift](/terragucci/guides/agent-fix-drift/) and [reviewing a pull request](/terragucci/guides/agent-review-a-pull-request/). It is off unless `agent.comment` is set; every other feature runs without an agent ([what needs an agent](/terragucci/#opt-in-coding-agent)).

## Result

A pull request comment such as:

```text
/terragucci agent rename var.bucket to var.bucket_name in app and its callers
```

A coding agent makes the change and terragucci commits it to the pull request's head. The commit is planned like any other; nothing is applied or merged.

## Prerequisites

| You need | Why |
|---|---|
| The pipeline from [Get your first plan note](/terragucci/getting-started/) | the agent jobs are written into it |
| On GitLab, [`comments:`](/terragucci/guides/re-plan-from-a-comment/) and its pipeline schedule | a merge request note starts no pipeline; the `comments` job reads `/terragucci agent` |
| An Anthropic API key in your forge's secrets | the default command runs Claude Code |
| A token for the agent's commits in your forge's secrets (step 1) | a commit sent with the job's own token starts no workflow run, so the change would not be planned |

## Steps

1. Make the agent's token. Keep it in a secret such as `AGENT_FORGE_TOKEN` and the model's key in `ANTHROPIC_API_KEY`.

**GitHub**

   | Setting | Value |
   |---|---|
   | Who | a machine user with write access, outside `CODEOWNERS` |
   | Token | fine-grained, for this repository alone |
   | Contents | read and write |
   | Pull requests | read and write |
   | Workflows | none, so GitHub refuses any change it sends to `.github/workflows/` |
   | Default branch ruleset | a pull request and one approval of the latest change required, with no bypass for the machine user |

**GitLab**

   | Setting | Value |
   |---|---|
   | Who | a bot user or project access token with the Developer role, outside `CODEOWNERS` |
   | Token scopes | `api` and `write_repository` |
   | Variable | `AGENT_FORGE_TOKEN`, masked; the model's key in `ANTHROPIC_API_KEY`, masked |
   | Default branch | protected, with the bot off the push and merge lists |

   GitLab also needs `comments:` beside the `agent` block. The `comments` job starts the agent's pipeline on the default branch with its own job token, so it runs as the user who owns the comments schedule.
**Forgejo**

   | Setting | Value |
   |---|---|
   | Who | a machine user added as a collaborator with Write access |
   | Token scopes | `write:repository` and `write:issue` |
   | Default branch | the machine user stays off the push, approval and merge allowlists |

2. Turn it on. Add the `comment` key to the `agent` block of `terragucci.yml`:

   ```yaml
   agent:
     via: forge
     token_env: AGENT_FORGE_TOKEN
     comment:
       key_secret: ANTHROPIC_API_KEY
       max_turns: 30
       timeout: 30
   ```

   `token_env` names the secret with the agent's token. `comment: true` takes every default, listed in [terragucci.yml keys](/terragucci/reference/config/#the-agent-comment).

3. Check the file and write the pipeline, then merge to the default branch, which comment workflows run from:

   ```bash
   npx terragucci config check
   npx terragucci init
   ```

4. Ask. Write `/terragucci agent` and the ask on one line. The reply links the commit and names the files it changed.

   The commit records the ask and who made it on which pull request:

## Agent permissions

| Job | Does | Holds |
|---|---|---|
| `agent` | checks the [`agent` column of the refusal table](/terragucci/reference/pipeline/#ignored-comments), checks out the head with no credentials kept, runs the agent, and keeps its changes as a patch | its own read-and-comment token, which the agent's step runs without; the model's key, in the agent's step alone |
| `agent-push` | applies the patch to the same head in a fresh container; refuses one that touches a [guarded path](/terragucci/reference/pipeline/#paths-an-agent-cannot-change), with a reply naming the paths; pushes any other as one commit without force | the agent's token |
| the plan job | plans the pushed change with its read-only role | the plan role |

On GitLab the `comments` job answers the note and starts a pipeline on the default branch with `TERRAGUCCI_AGENT_MR`, `TERRAGUCCI_AGENT_NOTE` and `TERRAGUCCI_AGENT_HEAD`. Both jobs run there from the default branch's pipeline file. Each reads the merge request and the note from GitLab again before it acts. GitLab hands every job the project's variables, so the agent runs under `env -i` and gets only the prompt and turn limit plus the model's key.

| Guard | What it stops |
|---|---|
| the ask reaches the agent as a prompt file (`TG_AGENT_PROMPT`), never on a command line | the ask running in a shell |
| the agent's step clears `GITHUB_TOKEN`, `FORGEJO_TOKEN`, `GITEA_TOKEN` and the runner's artifact and identity token variables; on GitLab it starts with an empty environment and a checkout whose remote holds no job token; neither agent job has a cloud role, whatever `oidc` says | the agent pushing, commenting or calling the cloud itself |
| `agent-push` refuses a patch that touches a guarded path: CI files (`.gitlab-ci.yml` and `.gitlab/` among them), `terragucci.yml`, [`chant.workspace.json`](/terragucci/concepts/glossary/#chantworkspacejson), `.chant/`, the signers file, the policy directory, `CODEOWNERS` and agent instruction files | the agent changing the pipeline, the gate, the signers or the policy |
| `agent-push` pushes to the same head, without force | a lost commit: when the agent fails, hits its turn limit, or the pull request moves, the branch stays as it was |
| the command below lets the agent edit files and run `terragucci config check` and `terragucci init --dry-run`, and loads no MCP server and none of the repository's Claude Code settings | any other command, web fetches and MCP tools |

The default command pins one release of Claude Code and runs it in print mode:

```text
npx -y @anthropic-ai/claude-code@2.1.290 -p --max-turns "$TG_AGENT_MAX_TURNS"
  --permission-prompts none --setting-sources user --strict-mcp-config --no-session-persistence
  --tools "Read,Edit,Write,Glob,Grep,Bash"
  --allowedTools "Read" "Edit" "Write" "Glob" "Grep" "Bash(terragucci config check)" "Bash(terragucci init --dry-run)"
  --disallowedTools "WebFetch" "WebSearch" "mcp__*" "Edit(.git/**)"
```

The flags are in the [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference).

## Use another agent

`command` takes any command line that reads a prompt on stdin and edits files in the working directory.

```yaml
agent:
  via: forge
  token_env: AGENT_FORGE_TOKEN
  comment:
    command: my-agent --non-interactive
    key_secret: MY_AGENT_KEY
```

| Variable | Holds |
|---|---|
| `TG_AGENT_PROMPT` | the prompt's path |
| `TG_AGENT_MAX_TURNS` | the turn limit |
| the `key_secret` name | the model's key, under its own name |

`agent-push` refuses a guarded path whichever agent wrote the patch.

## MCP or `--json`

| Where the agent runs | What it uses |
|---|---|
| in the `agent` job | the shell: `terragucci config check` and `terragucci init --dry-run`, which edit nothing. The default command loads no MCP server, and the job has no bucket credentials to give one |
| at your desk, before you ask | [`terragucci mcp`](/terragucci/guides/agent-read-over-mcp/) to read the pull request's plan reports (`index`, then `report`) and a root's last apply; the CLI with `--json` to check a config it wrote |

## Next

- [Re-plan a pull request from a comment](/terragucci/guides/re-plan-from-a-comment/) plans again without changing anything.
- [The generated pipeline](/terragucci/reference/pipeline/#the-agent-comment) lists the jobs and their tokens.

---

# Have a model review a pull request

Source: https://intentius.io/terragucci/guides/agent-review-a-pull-request/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/agent-review-a-pull-request/.
Add the `review` block to terragucci.yml, write the review instructions file, run `npx terragucci config check` and `npx terragucci init`, and open a pull request with the result.
List the secret I must set; do not create tokens or secrets yourself.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

One of the features that run a model ([what needs an agent](/terragucci/#opt-in-coding-agent)), off unless `review.agent` is set.

## Result

After each plan of a pull request, a note with the model's review under terragucci's first lines:

```markdown
### terragucci review of `3f9c2a1e`

Risk: **high**. A model compared the title and description with the diff, the plan note and the policy results. This note approves nothing.

Mismatches: the plan destroys `terraform_data.old`, which the description does not mention.

Questions: is `terraform_data.old` still read by anything?

risk: high
```

The note neither approves nor requests changes, and it sets no status. Reviewers read it beside the plan note. A policy can act on its risk when the pull request applies ([below](#risk-in-a-policy)).

## Prerequisites

| You need | Why |
|---|---|
| The pipeline from [Get your first plan note](/terragucci/getting-started/) | the review runs after the pull request's plan job |
| Actions on the default branch able to start a workflow on `workflow_run` (GitHub) or `pull_request_target` (Forgejo) | the review is a workflow of its own that the forge runs from the default branch |
| On GitLab, [`comments:`](/terragucci/guides/re-plan-from-a-comment/) and its pipeline schedule | a merge request's own pipeline runs the merge request's pipeline file, so the `comments` job starts each review in a pipeline of the default branch |
| Your model's API key in your forge's secrets, such as `ANTHROPIC_API_KEY` | the review runs on your model and your key |

## Steps

1. On the default branch, write `.terragucci/review.md` to tell the model what matters in this repository:

   ```markdown
   Treat a destroy or replace of a database, a bucket or a DNS zone as high risk.
   Every root under envs/prod/ needs a reason in the description.
   ```

   Only the default branch's copy counts; a pull request that edits it changes nothing until it merges, and its note says it edits the instructions.

2. Turn it on in `terragucci.yml`:

   ```yaml
   review:
     agent: true
     key_secret: ANTHROPIC_API_KEY
   ```

   Every key is in [terragucci.yml keys](/terragucci/reference/config/#the-review).

3. Check the file and write the pipeline, then open a pull request with the result:

   ```bash
   npx terragucci config check
   npx terragucci init
   ```

   `init` writes the review workflow, `.github/workflows/terragucci-review.yml` or `.forgejo/workflows/terragucci-review.yml`. The forge runs it from the default branch, so it first reviews pull requests opened after this one merges.

   GitLab gets the `review` and `review-note` jobs in `.gitlab/terragucci.yml`. Once a merge request's plan job ends, the next run of the comments schedule starts a pipeline on the default branch for its head, and edits the review note to say so; when the pipeline ends, the model's text replaces it.

## Model inputs

| Part | From |
|---|---|
| The title and description | the pull request, from the event (Forgejo) or the API (GitHub and GitLab) |
| The diff | `git diff` of the base branch and the head |
| The plan note | the plan job's report, from the pipeline's run of the head (on GitLab, the merge request's pipeline of the head), without its markers |
| The policy results | each planned root's result, denials and warnings, from the same report |
| The instructions | `review.instructions` (default `.terragucci/review.md`) on the default branch, read with `git show` |

The prompt marks everything but the instructions as written by the pull request's author, and tells the model to follow nothing in it. It asks for the risk, the mismatches between the description and the plan and any questions, ending on a line `risk: low`, `risk: medium` or `risk: high`. A review with no such line, or a command that fails, gives risk `unknown`.

## Job permissions

| Job | Does | Holds |
|---|---|---|
| `review` | checks out the head with no credentials kept, fetches the plan report, writes the prompt, unpacks the default branch's files into an empty directory and runs the review command there with the prompt on stdin; keeps what it prints | the job's token (read-only on GitHub), which the command's step runs without; the model's key, in that step alone |
| `review-note` | in a fresh container, posts the review as one note on the pull request, and edits that note on the next push | the job's token, to comment |

| Guard | What it stops |
|---|---|
| both jobs are in the default branch's review workflow, which GitHub runs on `workflow_run` and Forgejo on `pull_request_target`; on GitLab, in a pipeline of the default branch | a pull request editing the review it gets |
| the command's step clears `GITHUB_TOKEN`, `FORGEJO_TOKEN`, `GITEA_TOKEN` and the runner's artifact and identity token variables; on GitLab, where every job holds the project's variables, the command starts with an empty environment but for the prompt and the model's key; neither job has a cloud role | the model commenting, pushing or calling the cloud |
| the command runs in the default branch's files, not the checkout | a script the command names, or a setting file it reads, coming from the change |
| `review-note` turns every HTML comment in the review into text before it posts | a review that forges terragucci's markers, such as the plan note's |
| `review-note` posts an issue comment, never a pull request review | a review that approves |

## Other models

`command` takes any command line that reads the prompt on stdin and prints the review on stdout. The default is one pinned release of Claude Code in print mode with no tools:

```text
npx -y @anthropic-ai/claude-code@2.1.290 -p --max-turns 1 --permission-prompts none
  --setting-sources user --strict-mcp-config --no-session-persistence --tools ""
```

Another program, with its own key:

```yaml
review:
  agent: true
  command: my-reviewer --stdin
  key_secret: MY_MODEL_KEY
  timeout: 5
```

| Variable | Holds |
|---|---|
| `TG_REVIEW_PROMPT` | the prompt's path |
| the `key_secret` name | the model's key, under its own name |

## Risk in a policy

With `review.agent` and [`policy`](/terragucci/reference/policy/) set, each `tf-apply` wave passes the policy the review of the applied pull request's head as `input.review`:

```rego
package main

deny contains msg if {
  input.review.risk == "high"
  msg := sprintf("the review of pull request %d says risk high", [input.review.pull_request])
}
```

The policy gets the risk only from the review job's artifact in a run of the default branch's review workflow. On GitLab the review note names its review job, and the wave reads that job's artifact once GitLab says the job is `review` in a pipeline of the default branch. A note someone posts on the pull request or an artifact the pull request's own pipeline keeps is ignored. A denied wave applies nothing; a listed person can [override](/terragucci/reference/policy/#overriding-a-denial) one plan as for any denial. [`input.review`](/terragucci/reference/policy/#review) lists the fields.

## MCP or `--json`

The review command gets everything in its prompt and runs with no tools, so it needs neither. An agent at your desk that follows up on a review reads the pull request's plan reports through [`terragucci mcp`](/terragucci/guides/agent-read-over-mcp/) (`index`, then `report`), and checks a config it changes with `terragucci config check --json`.

## Next

- [The threat model](/terragucci/reference/threat-model/#job-access) lists the review jobs with the rest.
- [Have an agent change a pull request](/terragucci/guides/agent-change-a-pull-request/) runs a coding agent on a comment.

---

# terragucci.yml keys

Source: https://intentius.io/terragucci/reference/config/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/reference/config/.
Run `npx terragucci config check --json` on this repo's terragucci.yml and list each problem it finds.
Propose the smallest file that keeps current behavior, run config check again, and open a pull request with it.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

terragucci reads `terragucci.yml`, `.yaml`, `.json` or `.ts` from the repo root; two is an error. `terragucci config check` lists every problem.

## Schema

The file's JSON Schema is at [`https://intentius.io/terragucci/terragucci.schema.json`](/terragucci/terragucci.schema.json), and in the package as `@intentius/terragucci/terragucci.schema.json`. `config check` validates against it. The schema checks each key's type and values; rules across keys, and those that read the repo, are `config check`'s alone.

For completion and checks in an editor that runs the YAML language server, start the file with:

```yaml
# yaml-language-server: $schema=https://intentius.io/terragucci/terragucci.schema.json
binary: tofu
```

## Defaults with no file

| Setting | Default |
|---|---|
| Roots | every directory whose `*.tf` or `*.tofu` files declare a backend or configure a provider, or, in a Terragrunt repo, each unit `terragrunt find` lists |
| Binary | `.opentofu-version` gives `tofu`, `.terraform-version` gives `terraform`, then `.tofu` files, then the path, then `tofu` |
| Version | the repo's `.opentofu-version` or `.terraform-version`, then the one `required_version` pins exactly, or terragucci's default for the binary; a root that pins its own runs that one ([A version per root](#a-version-per-root)) |
| Forge | from a workflow directory already in the repo, or the host of its `origin` remote |
| Order | a root that reads another's state through `terraform_remote_state`, or with `binary: choudoufu` another estate's outputs through `terraform_estate_outputs`, applies after it |
| Gate | `on-destructive`, so a wave waits for an approval only when it destroys or replaces something |
| Drift | off |
| Runtime | your forge's CI |
| Reports | a CI artifact, linked from the pull-request note |

Running `init` again changes nothing unless the repo changed.

## A file for one repo

Put `terragucci.yml` at the repo root to change only what the defaults got wrong:

```yaml
binary: tofu
waves:
  canary: [envs/dev/core]
drift: "17 4 * * *"
```

## A file for many repos

In a [control repo](/terragucci/concepts/control-repo/), a project's keys override `defaults`; see [Govern many repos](/terragucci/guides/govern-many-repos/). `defaults` takes every key but `url`, which names one project's repo, and `rollouts`, which a control repo runs with `terragucci respond rollout` instead.

A key the control repo sets away from its default reaches each project one of two ways:

| How it reaches the project | Keys |
|---|---|
| `reconcile` writes it into the project's own `terragucci.yml`, which the jobs read | `policy`, `reports`, `approval`, `gate`, `roots`, `waves`, `parallelism`, `synth`, `steps`, `drift`, `cost`, `tips`, `runtime`, `telemetry`, `respond`, `decide`, `audit_region`, `modules` (with `modules.attest`, `modules.require`, `modules.trusted`, `modules.test` and `modules.registry`), `terragrunt`, `token_env`, `ephemeral`, `generate` (whose files `reconcile` also writes into the same pull request), `review` (its jobs are in the pipeline too) |
| in the pipeline `reconcile` writes | `binary`, `version`, `forge`, `apply` (with `apply.resume`), `locks`, `comments`, `gitlab`, `env`, `oidc`, `agent`, `atlantis_comments`, `dashboards`, `notify` (with `notify.webhook`) |

```yaml
defaults:
  binary: tofu
  gate: on-destructive
projects:
  github.com/acme/infra:
    roots: ["envs/*/*"]
  gitlab.example.com/platform/network:
    binary: terraform
    drift: "17 4 * * *"
  codeberg.org/acme/edge: {}
```

## A full example

Most settings here differ from their default, and [Keys](#keys) lists every one. Keep only the lines you need; this file passes `config check`.

```yaml
roots: ["envs/*/*"]
binary: tofu
version: 1.10.6
forge: forgejo
url: https://git.example.com:3000/acme/infra
gate: always
apply:
  when: merge                 # pull-request: see Apply before merge
waves:
  canary: [envs/dev/core]
drift: "17 4 * * *"
runtime: forge
reports:
  bucket: acme-terragucci-reports
  prefix: infra
  url: https://reports.example.com
  role: arn:aws:iam::111122223333:role/terragucci-reports
env:
  TF_LOG: WARN
telemetry:
  headers_secret: OTLP_HEADERS
  trace_url: https://grafana.example.com/explore?trace={trace_id}
token_env: FORGE_TOKEN
oidc:
  plan_role: arn:aws:iam::111122223333:role/terragucci-plan
  apply_role: arn:aws:iam::111122223333:role/terragucci-apply
parallelism: 8
terragrunt:                   # read in a Terragrunt repo only
  version: 1.1.6
atmos:                        # read in an Atmos repo only
  version: 1.230.1
policy:
  engine: conftest
  path: policy
  override: [github:alice]
modules:
  path: "modules/*"
  publish: git-tags
tips: false
respond:
  drift: attribute
  version-bump: suggest
agent:
  via: forge
  token_env: AGENT_FORGE_TOKEN
  comment: true
review:
  agent: true
decide:
  backend: laya
  url: http://decide:8790
audit_region: eu-west-1
dashboards: true
```

## Keys

| Key | Default | Meaning |
|---|---|---|
| `roots` | detected | globs of root directories. A Terragrunt repo's units are the ones `terragrunt find` lists, so `roots` there is a config error: leave units out with `terragrunt.exclude`. A [Terramate](/terragucci/guides/use-terramate/) repo's roots are its stacks, so `roots`, `synth`, `generate`, `rollouts` and a drift pull request are config errors there; leave a stack out with `.tmskip` |
| `synth` | none | the command that writes the roots, such as `npx cdktn synth`; the check, plan, apply, tips and drift jobs run it on their checkout before reading them, and a pull request plans only the synthesized roots whose output differs from the base's. With it, `rollouts`, `generate`, and a `drift` schedule under `respond.drift: pull-request` are config errors, since each edits the files the command writes, and the app sets backends, providers and `required_version` through its own constructs; see [Plan CDK Terrain stacks](/terragucci/guides/plan-cdk-terrain-stacks/) |
| `steps` | none | commands run before or after a root's `init`, `plan`, `apply` or `drift`, in the stage's own job: each has `run`, one of `before` and `after`, and optionally `name`, `roots` (globs) and `on_failure` (`fail`, the default, or `approve`, which holds the root's wave at its gate instead). Read from `terragucci.yml` at base. In a Terragrunt repo each moment runs once around the wave's `run --all`, in each unit the `roots` globs match, and `after: init` is refused; see [Run steps around a stage](/terragucci/guides/run-steps/) |
| `image` | terragucci's image for the binary | the image every job runs in, built `FROM` terragucci's image for the binary so the jobs keep terragucci and the binary; see [Run steps around a stage](/terragucci/guides/run-steps/#run-the-jobs-in-your-own-image) |
| `binary` | detected; see [Defaults with no file](#defaults-with-no-file) | `terraform`, `tofu` or [`choudoufu`](/terragucci/concepts/glossary/#choudoufu) |
| `forge` | read from the project's host | `github`, `gitlab` or `forgejo`, for a host terragucci cannot name |
| `gate` | `on-destructive` | `always`, `on-destructive` or `never`; see [Gate policy](/terragucci/reference/stages/#gate-policy). `on-destroy` is accepted as an older name for `on-destructive`, the name SQL Yodeler and chant use |
| `approval` | `ledger`; `sealed` when [`chant.workspace.json`](/terragucci/concepts/glossary/#chantworkspacejson) lists gates and the key is unset | what counts as a waiting wave's approval: `ledger`, any approval of its digest; `pr-review`, also a review of the merged head; `sealed`, only a sealed one. Read at base; see [Approval modes](/terragucci/guides/approve-a-wave/#approval-modes) |
| `apply` | `when: merge` | `when`, `merge`, `merge_token_env` and `requires`; see [Apply before merge](#apply-before-merge). `branches`: roots that apply from a branch other than the default; see [Apply from other branches](#apply-from-other-branches). `resume`: the minutes, 5 to 60, between runs of the [resume job](/terragucci/reference/pipeline/#resume-after-an-approval), which applies a waiting wave once its approval is on `chant/lifecycle`; off when unset |
| `locks` | `apply` | when a pull request locks the roots it reaches: `apply`, when it applies before merge or a writer comments `/terragucci lock`; `plan`, from its first plan (GitHub and Forgejo); see [Plan locks](#plan-locks) |
| `waves` | none | `canary`, a list of roots that go out first, as wave 1; `after`, roots that apply after others they do not read (plain roots; see [Root order](#root-order)); `jobs`, the most jobs one wave's roots or units spread across, 1 when unset (not with `apply.when: pull-request`; see [A wide wave across jobs](/terragucci/concepts/waves-and-approvals/#a-wide-wave-across-jobs)) |
| `notify` | none (off) | the secrets of a Slack (`slack`) or Teams (`teams`) incoming webhook, and `webhook` with `webhook_key` for a signed [`terragucci.notify/v1`](/terragucci/reference/notify-event/) event; an apply job posts a wave that waits, is refused or fails, and the drift job posts drift to Slack and Teams with a Re-plan button. A message approves nothing; see [Notify a chat channel](/terragucci/guides/notify-a-chat-channel/). `relay`: the name of [your relay](/terragucci/guides/approve-from-chat/), not a secret; a waiting wave's Slack message then carries Approve and Decline buttons, and its Teams card the reply that approves |
| `cost` | none (off) | a monthly cost estimate per root in the plan note: `true` runs Infracost in the plan job on the key in the secret `INFRACOST_API_KEY`; `key_secret` names another secret, and `command` runs another estimator that prints Infracost's JSON. Each `tf-apply` wave prices its plans too, for the policy's `input.cost`; `approve_above: <amount>`, read at base, makes a wave whose monthly change is over the amount wait for an approval whatever `gate` says ([Estimate the cost of a change](/terragucci/guides/estimate-cost/#hold-a-wave-over-an-amount)) |
| `drift` | `false` (off) | a cron schedule for `tf-drift`; see [Drift](/terragucci/reference/stages/#drift). A choudoufu root under live resource markers plans in full ([Live roots](/terragucci/guides/turn-on-drift-checks/#live-roots)) |
| `rollouts` | `false` (off) | a cron schedule for the rollout job, which opens the next wave of each rollout in flight once the last applied; `respond.rollout: off` leaves it out. Not in a control repo; see [Roll out a new module version](/terragucci/guides/roll-out-a-module-version/) for its token and the GitLab schedule |
| `comments` | `false` (off) | GitLab only: the cron of the comments schedule, whose pipelines answer `/terragucci` merge request notes; see [Re-plan from a comment](/terragucci/guides/re-plan-from-a-comment/) |
| `gitlab.token` | `unprotected` | GitLab only: `protected` keeps `GITLAB_TOKEN` (or the `token_env` variable, marked Protected and Masked) out of every merge request and branch pipeline; the comments job then posts the plan notes, and there is no fmt job. Needs `comments`; see [the threat model](/terragucci/reference/threat-model/) |
| `runtime` | `forge` | `forge`, the only value: every stage runs on the forge's CI; see [Runtimes](/terragucci/reference/runtimes/) |
| `reports` | none: the report is a CI artifact | `bucket` (`s3://<bucket>`, `gs://<bucket>` or `az://<account>/<container>`), `endpoint` (the store's address, for an S3-compatible store, an emulator or a sovereign cloud), `prefix`, `url` (the browser address links use, such as the [front door](/terragucci/guides/keep-reports-in-a-bucket/#5-serve-the-index)) and `role` (an AWS role ARN that writes, `s3://` only); see [Keep reports in a bucket](/terragucci/guides/keep-reports-in-a-bucket/) |
| `version` | the repo's version file, then the one every root pins exactly, else terragucci's default for the binary | the binary's version; as a map of root glob to version, the version each root it matches runs; see [A version per root](#a-version-per-root) |
| `generate` | none (off) | each plain root's `backend.tf`, `providers.tf` and `versions.tf`, which `terragucci generate` writes and `tf-check` holds to: `backend`, `providers`, `required_version` and, for Terragrunt units, `disable_init` for every root, then the same under `dirs` (root path globs) and `roots` (exact root paths); see [Generate backend and provider files](/terragucci/guides/generate-root-files/) |
| `env` | `{}` | environment variables every job gets; values only, never secrets |
| `pass` | none | `secrets` and `vars`: names of CI secrets and variables that the jobs that plan, apply and check drift get as environment variables of the same name, such as `TF_VAR_db_password`; never their values. On GitLab every job has the CI/CD variables already, so the key changes nothing there; see [Secrets and variables](#secrets-and-variables) |
| `runner` | the forge's: `ubuntu-latest` on GitHub, `docker` on Forgejo, no tags on GitLab | the runner each job runs on: a label, a list of labels, or on GitHub `group` with optional `labels`; or `default`, `plan`, `apply` and `drift`, each one of those. Written as `runs-on` on GitHub and Forgejo and `tags` on GitLab; see [Runners](#runners) |
| `url` | `https://<host>/<path>` | where a project lives, for a forge on another scheme or port |
| `telemetry` | none | `headers_secret`, the secret holding `OTEL_EXPORTER_OTLP_HEADERS`; `trace_url`, a trace link with `{trace_id}` |
| `token_env` | `GITHUB_TOKEN`, `GITLAB_TOKEN` or `FORGEJO_TOKEN`, by forge | the forge token `reconcile`, `rollout` and `respond --mode apply` use |
| `oidc` | none | plan and apply identities per cloud, and with `oidc.roles` AWS roles by root glob; see [Cloud roles over OIDC](/terragucci/reference/environment/#cloud-roles-over-oidc) |
| `parallelism` | 3 for GitLab-managed state, else 4 | roots planned at once, and applied at once in a wave; Terragrunt uses `terragrunt.parallelism`. Each root running starts its own providers: with the AWS provider, about 800 MB each, so 4 fit a 7 GB runner and 16 need about 13 GB |
| `terragrunt` | detected | Terragrunt settings: `version`, `exclude`, `parallelism`, `dependents`, `credentials` |
| `atmos` | detected | Atmos settings: `version`, the Atmos release every job installs (default: the one this terragucci release pins). Set only in a repo with `atmos.yaml` at its root, and never beside `terragrunt`; see [Use Atmos](/terragucci/guides/use-atmos/) |
| `policy` | none (off) | `engine` (`conftest` or `opa`), `path` (default `policy`), `namespace`, `input` (`plan` or `hcp`), [`source`](/terragucci/reference/policy/#a-shared-policy-source) (`git+https://<host>/<path>@<ref>`), [`override`](/terragucci/reference/policy/#overriding-a-denial) (who may let one denied plan through, read at base; unset, nobody); the [base branch's key](/terragucci/reference/policy/#the-base-branch-decides) decides |
| `modules.path` | `modules/*` | a glob of the directories that hold your modules |
| `modules.publish` | none | an `oci://` registry, `git-tags`, or a list of both; turns on `tf-publish` |
| `modules.attest` | none (off) | `true`, or `key` (default `cosign.pub`): sign each release, attest its provenance and SBOM, and record it in the release ledger; see [Attest each release](/terragucci/guides/publish-modules/#attest-each-release) |
| `modules.require` | none (off) | `attested`: `tf-check` and `tf-plan` refuse a root that pins a release of a checked source unless it verifies; `tf-plan` reads it at base. terragucci's CI images carry the HCL parser it reads pins with; elsewhere, `npm i -D @cdktn/hcl2json`. See [Require attested releases](/terragucci/guides/publish-modules/#require-attested-releases) |
| `modules.trusted` | none | publishers in other repos that `require` checks: each a `source` (an `oci://` prefix or a git URL), the `key` (a path to their `cosign.pub` in this repo) and the `ledger` (the git URL whose `chant/lifecycle` holds their release ledger) |
| `modules.test` | `false` (off) | `true`: the binary's `test` runs on each module before a release of it publishes, and a module with no tests, or whose tests fail, is refused; see [Test each release](/terragucci/guides/publish-modules/#test-each-release) |
| `modules.registry` | none | write each release as the module registry protocol's static files: `url` (the `https://` host that serves them), `namespace`, `bucket` (`s3://`, `gs://` or `az://`) or `dir`, and optionally `endpoint`, `prefix`, `namespaces` (a tag prefix to a namespace), `system` (default `generic`) and `download` (`tarball`, the default, `git-tags` or `oci`); see [Serve a module registry](/terragucci/guides/publish-modules/#serve-a-module-registry) |
| `tips` | `true` | advice on pins, lock files and rollout setup, in the report and the dry run |
| `respond` | a response per event | how terragucci answers each pipeline event; see [Responses to pipeline events](/terragucci/reference/responses/) |
| `agent` | none | `via` (`forge`), `token_env`, [`comment`](#the-agent-comment) and [`drift`](#the-drift-agent) |
| `atlantis_comments` | `false` (off) | `true`: `atlantis plan` and `atlantis apply` comments work as `/terragucci plan` and `/terragucci apply`, with the same checks; see [Comment forms](/terragucci/guides/re-plan-from-a-comment/#comment-forms) |
| `review` | none (off) | `agent`, `command`, `key_secret`, `instructions`, `timeout`: a model reviews each pull request's description against its plan; see [The review](#the-review) |
| `decide` | none | the typed-decision service a few responses may ask; see [The decide block](#the-decide-block) |
| `audit_region` | the `aws` CLI's region | the AWS region whose CloudTrail drift attribution reads |
| `dashboards` | `false` (off) | `true`, or `dir`, `prometheus`, `tempo`, `folder`, `path`, `drift_age`, `wave_wait`, `schedule`; see [Dashboards](/terragucci/reference/observability/#dashboards-and-alerts) |
| `ephemeral` | none (off) | `roots`, root globs each pull request gets a copy of under state keys of its own, `ttl` (`<n>m`, `<n>h` or `<n>d`, default `24h`) and `sweep` (minutes between the sweep's runs, 5 to 60, default 30); read at base; see [Ephemeral environments](#ephemeral-environments) |
| `own_jobs` | none | jobs of your own that `init` and `reconcile` write into the generated pipeline after terragucci's, as they are: a map of job name to job in the forge's syntax, or the path of a YAML file in the repo that holds one; see [Jobs of your own](#jobs-of-your-own) |

`terragucci config check` rejects a key this table does not list and names the keys it accepts.

## A version per root

A plain root or a Terragrunt unit can run its own OpenTofu or Terraform version, so one wave plans and applies roots on different versions. The first of these that names an exact version picks it:

| Order | Where | Example |
|---|---|---|
| 1 | `version` in `terragucci.yml` as a map, the first glob the root's path matches | `"envs/legacy/*": "1.9.1"` |
| 2 | a `.opentofu-version` (`tofu`) or `.terraform-version` (`terraform`) file in the root | `1.10.6` |
| 3 | an exact `required_version` in the root | `required_version = "1.10.6"` |

```yaml
binary: tofu
version:
  "envs/legacy/*": "1.9.1"
  envs/edge: "1.11.2"
```

A root that pins nothing runs the version every job runs. A pin that is that version uses the job's binary as it is. Any other pin is installed in the job for the roots that pin it, checked against the release's SHA256SUMS, once per version, under `TOFU_INSTALL_DIR` by version, so a runner that keeps that directory reuses it. A version file that names no exact version (`latest`, `min-required`) and a `required_version` range pin nothing. The [report](/terragucci/reference/report-schema/) names each root's binary, version and pin, and so does the plan note once a root pins.

A map of versions goes in the repo's own `terragucci.yml`, which the jobs read; in a control repo, `version` is one version. Only `tofu` and `terraform` take pins. A Terragrunt unit is pinned the same ways. An exact `terragrunt_version_constraint` in its own `terragrunt.hcl` also pins the Terragrunt release that runs it, and the job installs that release like any other pin. One `run --all` runs one Terragrunt and one binary, so a wave whose units pin different releases runs as one `run --all` per pair of releases. Run `npx terragucci init` again after you add or change a pin, so the check job validates each root with its own version. With [`generate`](/terragucci/guides/generate-root-files/#the-version-each-directory-declares) set, each root's generated `required_version` is the version this map gives it, unless `generate` sets one.

## Root order

Plain roots apply in waves cut from their `terraform_remote_state` reads. `waves.after` orders roots that read nothing of each other: each key is a root or glob, and its list names the roots or globs it applies after.

```yaml
waves:
  after:
    app: [database]
    database: [network]
```

`network`, `database` and `app` then apply in three waves. The order counts everywhere a read does:

- a pull request that changes `network` plans `database` and `app` too, and its blast radius and locks take them
- each wave waits for the waves before it, behind their gates
- the report lists the order under `roots[].dependencies`

A root it orders but does not read plans on its own, and is never held back for an upstream with no state yet. A cycle, or a key or root that matches no root, is a config error that names them. A Terragrunt, Atmos or Terramate repo states its order in its own files, so `waves.after` there is a config error naming where. In a control repo, `waves.after` goes in `defaults` or a project's block, and `reconcile` writes it into the project's file.

## Apply before merge

```yaml
apply:
  when: pull-request   # default: merge
  merge: auto          # default: manual
  merge_token_env: MERGE_TOKEN   # the secret the merge is made with
  requires: [approved, mergeable, undiverged, checks]   # the default: all four
```

| Setting | Does | Allowed on |
|---|---|---|
| `when: merge` | only merged code applies, and the apply role never meets a pull request's code | every forge |
| `when: pull-request` | a writer's `/terragucci apply [wave-<n>]` on the open pull request applies its head, and its roots stay [locked](/terragucci/guides/apply-before-merge/#locks) until merge or close; after the merge, `terragucci/apply` fails if any root still plans a change | every forge, plain roots and Terragrunt repos, not with `waves.jobs`; on GitLab it needs `comments` and `merge_token_env` ([GitLab](#apply-before-merge-on-gitlab)) |
| `merge: manual` | a person merges | `when: pull-request` only; `config check` refuses `merge` without it |
| `merge: auto` | `pr-merge` merges once every wave applied, never after a partial apply | `when: pull-request` only |
| `merge_token_env` | the secret the merge is made with; only `pr-merge`, which runs no pull request code, gets it; on GitLab the `comments` job too, which starts the apply pipeline with it | required on Forgejo with `merge: auto`, and on GitLab with either `merge` |
| `requires` | what an open pull request needs before `/terragucci apply` applies it; see the next table | `when: pull-request` only; with `merge: auto` it must list `approved` |

| `requires` entry | The open pull request needs |
|---|---|
| `approved` | an approval of its head by a reviewer other than its author, and no reviewer whose last review asks for changes; on GitLab, an approval by a Developer or above after its latest push |
| `mergeable` | the forge to say it merges: no conflicts with the default branch, on GitHub no branch protection blocking it, on GitLab a `detailed_merge_status` of `mergeable` |
| `undiverged` | its head to contain the default branch as it is now |
| `checks` | every status and check on its head to have passed |

Leaving an entry out drops that check, and `requires: []` drops all four. These stay whatever `requires` lists:

| Always checked | The open pull request needs |
|---|---|
| `terragucci/plan` | to have passed on its head; a policy denial fails it |
| the pipeline file | to be left alone by the change |
| locks | no other open pull request holding a lock on a root it reaches |

### Apply before merge on GitLab

A merge request note starts no pipeline, and a merge request's own pipeline runs its own `.gitlab-ci.yml`. Instead, the `comments` job reads `/terragucci apply` and starts a pipeline on the default branch, whose `mr-apply` job applies the head.

```yaml
forge: gitlab
comments: "*/5 * * * *"
apply:
  when: pull-request
  merge: auto                               # or manual
  merge_token_env: TERRAGUCCI_MERGE_TOKEN   # required on GitLab
```

| Setting | Why |
|---|---|
| `comments` | the schedule whose job reads the note |
| `merge_token_env` | a CI/CD variable with a token whose role may merge into the default branch: only such a token may start a pipeline there, and with `merge: auto` it merges |
| `forge: gitlab` | needed with `merge: manual`, so `config check` knows the token is not only for merging |

Without `comments` or `merge_token_env`, `config check` and `init` refuse `when: pull-request` on GitLab. [Apply a pull request before it merges](/terragucci/guides/apply-before-merge/) has the variable's settings.

:::caution
On GitHub, `mergeable` reads `mergeable_state: blocked`, so a required status that only the apply posts (such as `terragucci/apply`) blocks every apply. Leave it out of branch protection.
:::

Everything that decides an apply (gate, approval mode, signers, this file) comes from the default branch. [When a comment runs nothing](/terragucci/reference/pipeline/#ignored-comments) lists every check an apply comment must pass.

Unmerged pull request code runs with the apply role. Forks never apply; require reviews in branch protection. [What the pull request's code can reach](/terragucci/reference/pipeline/#pull-request-code-access).

## Apply from other branches

```yaml
apply:
  branches:
    release: ["envs/prod/*"]
    staging: ["envs/staging/*"]
```

Each key is a branch, and its list holds root globs: a push to `release` applies only the roots under `envs/prod/`. Waves and their approvals work as on the default branch, and `terragucci approve wave-<n>` approves the waiting wave's plans whichever branch it waits on. `/terragucci apply` on a pull request merged into the default branch also skips every root a glob here matches.

| On a push to | Applies |
|---|---|
| the default branch | every root no branch's glob matches |
| a branch named here | only the roots its globs match |
| any other branch | nothing |

The waves are cut from the roots the branch applies, so a branch's wave 1 holds its first roots in apply order. A wave with nothing to apply on that branch passes without planning.

In a Terragrunt repo the globs match unit paths, such as `release: ["live/prod/**"]`. A push to `release` applies those units in their own dependency layers, each behind its gate, cut from `terragrunt find` as every Terragrunt wave is; a unit there that depends on a unit the default branch applies plans against that unit's applied state.

Drift checks run each root from the branch that applies it, so the difference between the branches is not drift ([Roots another branch applies](/terragucci/guides/turn-on-drift-checks/#roots-another-branch-applies)).

The [resume job](/terragucci/reference/pipeline/#resume-after-an-approval) applies the default branch's waiting waves only. A wave waiting on a branch named here applies when its run runs again: `terragucci approve` re-runs it on GitHub and GitLab, and on Forgejo the branch's next push runs it.

`config check` refuses a glob listed under two branches, and `apply.branches` with `apply.when: pull-request`, where a push applies nothing. Run `npx terragucci init` after a change to the map: the apply jobs carry it. The fmt job never commits to a branch named here.

## Ephemeral environments

```yaml
ephemeral:
  roots: ["envs/preview/*"]
  ttl: 24h
```

Each open pull request gets its own copy of the roots `roots` matches and applies it from its head. A copy's state is the root's own backend with `-pr-<n>` added to the key: `envs/preview/app/terraform.tfstate` becomes `envs/preview/app/terraform-pr-12.tfstate`, and a `gcs` prefix `preview/app` becomes `preview/app-pr-12`. The root keeps its own state, and its own plan and apply waves, as before.

| Event | What happens |
|---|---|
| a pull request opens, reopens or gets a push | its copy plans and waits at gate `tf-ephemeral pr-<n>` as `gate` says, then applies; the copy expires `ttl` after the last apply that changed it |
| the pull request closes or merges | its copy is destroyed: a `plan -destroy` of each root, applied in reverse order, from the commit the copy applied; on GitLab, which starts no pipeline when a merge request closes, at the next sweep |
| `ttl` passes | the sweep destroys the copy the same way, whether the pull request is open or not |

Every apply and destroy is a line in `_gates/tf-ephemeral/done.jsonl` on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle), which the [audit trail](/terragucci/reference/audit-trail/) lists as `ephemeral-apply` and `ephemeral-destroy`. The [estate page](/terragucci/guides/see-every-project/) lists each live copy and its expiry when `reports` is set.

terragucci runs no CLI workspaces, so a copy uses a state key suffix instead. A suffixed key is a separate state, and its lock file and the bucket listing show it by name. A copy works with an `s3`, `azurerm` or `gcs` backend, and a `local` one; a root on another backend or in HCP Terraform (a `cloud` block) fails its job with a config error naming it.

In a Terragrunt repo `roots` names units, and each unit's `remote_state` key must read `get_env("TERRAGUCCI_EPHEMERAL_SUFFIX", "")`, which the job sets to `-pr-<n>`; a unit whose prepared backend does not carry the suffix fails the job with a config error before anything plans. The `terragucci.hcl` that `generate` writes reads it already. With `synth`, the job runs the command in the pull request's checkout before it finds the roots, and again on the applied commit before a destroy. `config check` refuses `ephemeral` on GitLab with `gitlab.token: protected`, where no merge request pipeline holds the token that records the copy. The binary makes no difference: OpenTofu, Terraform and choudoufu each take a copy. The default branch supplies these settings, so a pull request cannot widen `roots` or lengthen `ttl` for its own copy. Run `npx terragucci init` after adding the key: it writes the jobs. [Ephemeral environments per pull request](/terragucci/guides/ephemeral-environments/) walks through it.

## Runners

```yaml
runner:
  default: [self-hosted, linux]
  apply: [self-hosted, prod]   # the jobs that hold the apply role
```

A job runs on its stage's runner, or `default` when its stage has none; [Runners](/terragucci/reference/pipeline/#runners) lists the jobs in each stage. `runner: self-hosted` puts every job on one label. A list asks for a runner that carries every label in it.

| Forge | What `init` writes | Not accepted |
|---|---|---|
| GitHub | `runs-on`: the label, the list, or `group` and `labels` | |
| Forgejo | `runs-on`: the label or the list as given; GitHub's hosted labels, such as `ubuntu-latest`, become `docker` | `group` |
| GitLab | `tags`: the label or the list | `group` |

A project's `runner` in a control repo replaces the defaults' whole. Run `npx terragucci init` after a change; [Self-hosted runners](/terragucci/guides/add-to-a-repo/#self-hosted-runners) covers what the runner needs.

## Secrets and variables

```yaml
pass:
  secrets: [TF_VAR_db_password]
  vars: [TF_VAR_region]
```

Each name reaches the plan, apply and drift jobs as an environment variable of that name, read from `secrets.<name>` or `vars.<name>`; [Secrets and variables you pass](/terragucci/reference/environment/#secrets-and-variables-you-pass) lists the jobs. `config check` refuses a value in place of a name, a name listed twice or also set in `env`, and a name the forge or terragucci keeps for itself: one that starts with `GITHUB_`, `GITEA_`, `FORGEJO_`, `TG_` or `TERRAGUCCI_`, and `TF_IN_AUTOMATION` and `TF_INPUT`.

## Jobs of your own

`init` writes the whole pipeline file each time it runs, so a job added to that file by hand is gone after the next `init`. Name the job under `own_jobs` and `init` writes it again each time, after its own jobs:

```yaml
own_jobs: ci/own-jobs.yml   # or the jobs themselves, as a map
```

```yaml
# ci/own-jobs.yml
notify-done:
  needs: apply-wave-2
  runs-on: ubuntu-latest
  steps:
    - run: echo "wave 2 applied"
```

| Forge | Where the jobs go |
|---|---|
| GitHub | under `jobs:` in `.github/workflows/terragucci.yml` |
| Forgejo | under `jobs:` in `.forgejo/workflows/terragucci.yml` |
| GitLab | at the top level of `.gitlab/terragucci.yml`, which `.gitlab-ci.yml` includes |

Each job keeps every key and value the file gives it in the forge's own syntax; comments in the file are dropped, and `init` checks only the job's name. A name terragucci gives one of its own jobs is refused, and so is a GitLab keyword such as `variables`. Since they share terragucci's run, `needs` may name a wave's job and an artifact download reads that run's reports. [Have an agent summarize a refused wave](/terragucci/guides/agent-refused-wave/) adds its job this way.

## Plan locks

```yaml
locks: plan   # default: apply
```

| Setting | A pull request locks its roots | Allowed on |
|---|---|---|
| `locks: apply` | when it applies before merge, or a writer comments `/terragucci lock` | every forge |
| `locks: plan` | from its first plan, and again on each push or `/terragucci plan` | GitHub and Forgejo, with either `apply.when`; `init` and `config check` refuse it on GitLab, where no merge request event runs a job from the default branch |

With `locks: plan`, `init` adds the `pr-lock` job ([the generated pipeline](/terragucci/reference/pipeline/#plan-locks)). A second pull request that reaches a locked root gets a failing `terragucci/lock` status, and branch protection can require that status. [Locks](/terragucci/guides/apply-before-merge/#locks) lists what takes and releases a lock.

## A TypeScript file

`terragucci.ts` (`TerragucciConfig`) is folded without running; reading the environment is refused. It needs `npm i -D @intentius/tsad-reference`.

## The terragrunt block

```yaml
terragrunt:
  version: 1.1.6
  exclude: ["live/sandbox/**"]
  parallelism: 16
  dependents: follow
  credentials:
    "live/prod/**": { plan: arn:aws:iam::111:role/plan, apply: arn:aws:iam::111:role/apply }
```

| Key | Default | Meaning |
|---|---|---|
| `version` | the version `terragrunt_version_constraint` pins exactly, or terragucci's | the Terragrunt release the jobs run |
| `exclude` | none | unit globs to leave out; `catalog/**` and `.terragrunt-cache` are always left out |
| `parallelism` | 3 for GitLab-managed state, else 16 | how many units one `run --all` runs at once; each unit running starts its own providers, about 800 MB each with the AWS provider, so 16 need about 13 GB: set 4 on a 7 GB runner |
| `dependents` | `plan` | `plan` previews a changed unit's dependents in the pull request, on the planned outputs of the units they read, provisional and undigested; `follow` leaves them to plan once what they read applies |
| `credentials` | none | AWS roles by unit glob; see [Credentials](/terragucci/reference/pipeline/#terragrunt) |

Terragrunt 1.1 or later is required; see [Use Terragrunt](/terragucci/guides/use-terragrunt/).

## The agent comment

`agent.comment` lets a writer ask an agent to change a pull request; GitHub and Forgejo only.

```yaml
agent:
  via: forge
  token_env: AGENT_FORGE_TOKEN
  comment:
    command: claude -p --max-turns "$TG_AGENT_MAX_TURNS"
    key_secret: ANTHROPIC_API_KEY
    max_turns: 30
    timeout: 30
```

`comment: true` takes defaults; `agent.token_env` is the push token's secret name.

| Key | Default | Meaning |
|---|---|---|
| `command` | Claude Code in print mode | run in the checkout, prompt on stdin |
| `key_secret` | `ANTHROPIC_API_KEY` | the secret holding the model's API key, given to the agent's step alone |
| `max_turns` | 30 | the turn limit, passed to the command as `TG_AGENT_MAX_TURNS` |
| `timeout` | 30 | minutes before the agent's job is stopped |

The agent's jobs get no cloud credentials. On GitLab it needs `comments`, whose job starts the agent's pipeline on the default branch. [The jobs](/terragucci/reference/pipeline/#the-agent-comment).

## The drift agent

`agent.drift` runs an agent when the drift job opens the drift issue, and opens a pull request with what it changed; GitHub and Forgejo only. [Have an agent fix drift](/terragucci/guides/agent-fix-drift/) sets it up.

```yaml
drift: "0 6 * * *"
respond:
  drift: off
agent:
  via: forge
  token_env: AGENT_FORGE_TOKEN
  drift:
    key_secret: ANTHROPIC_API_KEY
    max_turns: 30
    timeout: 30
```

Its keys and defaults are `agent.comment`'s, and `drift: true` takes them all; `agent.token_env` is the secret of the token that pushes the branch and opens the pull request. It needs a `drift` schedule and `respond.drift` set to `attribute` or `off`, since the agent's pull request takes the place of the codified one. Neither drift agent job gets cloud credentials, and `init` refuses `agent.drift` on GitLab. [The jobs](/terragucci/reference/pipeline/#the-drift-agent).

## The review

`review.agent` adds two jobs after a pull request's plan. A model compares the title and description with the diff, the plan note and the policy results, then the pipeline posts its review as a note. GitHub and Forgejo only; [Have a model review a pull request](/terragucci/guides/agent-review-a-pull-request/).

```yaml
review:
  agent: true
  command: my-reviewer --stdin
  key_secret: ANTHROPIC_API_KEY
  instructions: .terragucci/review.md
  timeout: 10
```

| Key | Default | Meaning |
|---|---|---|
| `agent` | `false` | `true` turns the review on; the other keys need it |
| `command` | Claude Code in print mode with no tools | run in the default branch's files with the prompt on stdin; what it prints is the review |
| `key_secret` | `ANTHROPIC_API_KEY` | the secret holding the model's API key, given to the command's step alone |
| `instructions` | `.terragucci/review.md` | the instructions file, read from the default branch only |
| `timeout` | 10 | minutes before the review job is stopped |

Neither review job gets cloud credentials, and the command's step gets no forge token. GitLab runs each review in a default-branch pipeline that the `comments` job starts. With `policy` set, each `tf-apply` wave reads the review's risk as [`input.review`](/terragucci/reference/policy/#review).

## The decide block

Some responses can ask a typed-decision model about free text; with no `decide` block, nothing is asked.

```yaml
decide:
  backend: laya
  url: http://decide:8790
  thresholds: { noul: 0.8, choice: 0.7 }
```

| Key | Default | Meaning |
|---|---|---|
| `backend` | required | `laya` (the `terragucci-decide` image), `von`, `decider` or `jev` |
| `url` | required, except `jev` | the service's base URL; `jev` defaults to `https://api.typesafe.ai` |
| `model` | required, except `laya` | a pinned version such as `jev-1.13.0`; `jev-latest` is refused |
| `token_env` | none, required for `jev` | the bearer token's variable |
| `thresholds` | `noul` 0.8, `choice` 0.7, `score` 0.7 | the probability an answer needs before a response acts on it |

terragucci ignores an answer that is weak or missing or comes from another model. A decision never approves or applies anything and never resolves a gate; the model reads only the redacted report.

## Parameters

None. [`terragucci approve`](/terragucci/reference/cli/#approve) writes approvals to [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle). A local run can narrow:

```bash
terragucci plan --project github.com/acme/infra --root envs/dev/core
```

Nothing that changes what an approval covers can be passed at run time.

---

# CLI commands

Source: https://intentius.io/terragucci/reference/cli/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/reference/cli/.
Run `npx terragucci config check` and `npx terragucci init --dry-run --json` in this repo and tell me the roots, binary and forge it found, and any config problem, with the exit code of each.
Read only. Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

Run `npx terragucci <command>` from a repo's root; a generated pipeline calls the same commands.

| Command | Does |
|---|---|
| `init` | finds roots, binary and forge, and writes the pipeline; under `approval: sealed`, also [`chant.workspace.json`](/terragucci/concepts/glossary/#chantworkspacejson) |
| `import` | writes `terragucci.yml` from an `atlantis.yaml`, a `digger.yml` or a Terragrunt Scale `.gruntwork`, or from the workspaces of HCP Terraform, OTF or Scalr, and prints what became of each setting |
| `reconcile` | from a [control repo](/terragucci/concepts/control-repo/), opens a pull request in each project that needs a change |
| `generate` | writes each root's backend, provider and version files from the [`generate` key](/terragucci/guides/generate-root-files/), and in a Terragrunt repo `terragucci.hcl`, which each unit includes; `--check` refuses one that differs, and the generated `tf-check` job runs it |
| `estate` | writes one page for every project, `estate.html`, `estate.json` and `dora.json`, to the reports bucket, and prints a link to it: presigned on S3, a signed URL on GCS, a SAS on Azure Blob |
| `audit` | appends every approval, apply, policy override and refused wave across the projects to the [audit trail](/terragucci/reference/audit-trail/), `audit.jsonl` in the reports bucket, with its page and a link to it; `--check` reports what the record lacks |
| `plan` | plans every root and prints the result |
| `stage tf-plan` | plans the roots a change reaches, groups them, and writes the report |
| `publish` | publishes each changed module at a new version |
| `verify-release` | checks one published version of a module: its signature, provenance and SBOM, and its record in the release ledger |
| `rollout` | moves a module's or provider's pin one wave at a time |
| `respond` | runs the response to a pipeline event |
| `comment` | reads a `/terragucci plan [root]` or `/terragucci agent <ask>` pull request comment, polls GitLab merge request notes, and pushes an agent's change; the generated pipeline runs it |
| `comment-apply` | reads a `/terragucci apply [wave-<n>]`, `/terragucci lock` or `/terragucci unlock` comment; the generated pipeline runs it |
| `pr-lock` | takes or releases a pull request's plan locks under `locks: plan`; the generated pipeline runs it |
| `approve` | approves a waiting wave: finds it on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle), prints what it does and records an approval of its digest, with `--sign` under `approval: sealed`; also approves a migration, a state export, a lock release and a pull request environment; a person runs it |
| `override` | overrides a policy denial of one root's plan: finds the denial a `tf-apply` wave recorded, checks the rules named are the ones that denied it, and records the override with the reason; a person `policy.override` lists runs it |
| `approval-status` | with `approval: pr-review`, posts `terragucci/approval` on a pull request's head: pending while a wave the gate will hold has no approving review of that head; the generated pipeline runs it |
| `plan-note` | on GitHub and Forgejo, posts the plan job's note and `terragucci/plan` from its report, read as data; the generated `plan-note` and `replan-note` jobs run it |
| `notify` | posts a wave that waits, is refused or fails to the Slack, Teams and generic webhooks `notify` names, and drift to Slack and Teams; the generated apply and drift jobs run it |
| `relay` | serves the Approve and Decline buttons of Slack and Teams messages, in your own cloud |
| `query` | runs one SQL statement over the inventory, changes, history, audit trail and state edges in the reports bucket, on your machine, and prints the rows |
| `mcp` | a read-only MCP server on stdio over what terragucci wrote to the reports bucket and the repo, for a coding agent |
| `view` | runs [behold](https://intentius.io/behold/using/terragucci/) on your machine over the repo and its reports bucket: the roots as one graph, each resource marked with what the newest runs found; `--export` writes a static copy |
| `drift-agent` | writes the drift agent's prompt and opens a pull request with its change, with [`agent.drift`](/terragucci/guides/agent-fix-drift/); the generated pipeline runs it |
| `pr-merge` | merges a pull request every wave of which applied before merge, with `apply.merge: auto`; the generated pipeline runs it |
| `config check` | validates the config file and lists every problem, then prints the approval mode in force and where it comes from; with `oidc.roles`, the state each role reaches, and a warning for each role that reaches another environment's state |
| `state export` | asks for one version of a root's state and, once someone else approved the request, downloads it to your machine and records who exported what on `chant/lifecycle`; a person runs it |
| `check-root`, `check-pins`, `check-policy` | the steps of `tf-check` beyond the format check; the generated pipeline runs them |
| `resume` | applies a waiting wave once its approval stands, or the rest of a killed approved apply; the generated resume job runs it |
| `ephemeral` | applies a pull request's copy of the [ephemeral](/terragucci/reference/config/#ephemeral-environments) roots, destroys it on close, and sweeps the copies whose TTL passed; the generated pipeline runs it |
| `unlock-state` | releases a root's state lock a killed job left, once no run that may hold it is alive and an approval of its lock ID stands, and records the release; a person runs it |
| `auth-provider` | internal: Terragrunt's `auth-provider-cmd`, which the generated Terragrunt pipeline runs |
| `terramate generate` | internal: fails on stale [Terramate](/terragucci/guides/use-terramate/) generated code (`terramate generate --detailed-exit-code`), then writes each stack's order and inputs beside it; every job of the generated Terramate pipeline runs it first |
| `atmos write` | internal: writes each Atmos instance to `<stack>/<component>` from `atmos describe stacks`; every job of the generated [Atmos](/terragucci/guides/use-atmos/) pipeline runs it first |
| `profiles` | internal: prints the local stack profiles a config needs, `aws` and each project's forge |
| `install` | fetches a release of OpenTofu, Terraform, Terragrunt, Atmos, [choudoufu](/terragucci/concepts/glossary/#choudoufu) or Infracost, verified against its checksums |

## init

```bash
terragucci init [--forge github|gitlab|forgejo] [--binary tofu|terraform|choudoufu] [--approval ledger|pr-review|sealed] [--signer <principal>] [--force] [--dry-run]
```

| Flag | Meaning |
|---|---|
| `--forge` | the forge, when the remote cannot tell |
| `--binary` | the binary, when detection picks the wrong one: `tofu`, `terraform` or `choudoufu` |
| `--approval` | `ledger`, `pr-review` or `sealed`, when the config names no mode; see [Approval modes](/terragucci/guides/approve-a-wave/#approval-modes) |
| `--signer` | under `approval: sealed`, write the first line of `.chant/allowed_signers` for this principal from `git config user.signingkey`, when the file does not exist |
| `--dry-run` | compute everything and write nothing |
| `--force` | overwrite a pipeline file terragucci did not write; on GitLab that is `.gitlab/terragucci.yml`, never your `.gitlab-ci.yml` |

A flag detection would not reach goes into a new `terragucci.yml`. An existing config file is never edited: `init` exits 2 and names the line to add, such as `binary: terraform`. A key already set there wins.

The approval mode decides what else `init` writes.

| Mode | `init` also |
|---|---|
| `ledger` (the default) | writes no `chant.workspace.json`; with `approval: ledger` set, drops the wave gates an earlier `init` listed under [`identity.gates`](/terragucci/concepts/glossary/#identitygates) |
| `pr-review` | the same as `ledger`; on GitHub and Forgejo adds the `approval` job and the `terragucci/approval` status ([the pipeline](/terragucci/reference/pipeline/#statuses-and-stale-plans)) |
| `sealed` | writes [`chant.workspace.json`](/terragucci/concepts/glossary/#chantworkspacejson) with each wave's gate (`wave-1`, `wave-2`) under `identity.gates`, so a wave counts only an approval sealed with `terragucci approve --sign`; an existing file gains missing gates |

[Approve a waiting wave](/terragucci/guides/approve-a-wave/) sets up the signers file.

## import

```bash
terragucci import atlantis [<file>] [--forge github|gitlab|forgejo] [--apply-when merge|pull-request] [--force] [--dry-run]
terragucci import digger [<file>] [--forge github|gitlab|forgejo] [--apply-when merge|pull-request] [--force] [--dry-run]
terragucci import spacelift [<file>] [--forge github|gitlab|forgejo] [--apply-when merge|pull-request] [--force] [--dry-run]
terragucci import env0 [<file>] [--forge github|gitlab|forgejo] [--apply-when merge|pull-request] [--force] [--dry-run]
terragucci import terragrunt-scale [<dir>] [--force] [--dry-run]
```

Reads the file named, else `atlantis.yaml` (or `atlantis.yml`), or OpenTaco's `digger.yml` (or `digger.yaml`), and writes `terragucci.yml` by the tables of [Coming from Atlantis or OpenTaco](/terragucci/guides/coming-from-atlantis-or-opentaco/). Each setting the file carries is printed under one of four headings, quoting the guide's row:

| Heading | The setting |
|---|---|
| Written to terragucci.yml | became a key, such as a project's `dir` in `roots` |
| Done by terragucci with no key | needs no key, such as `autoplan.when_modified` |
| Not mapped | has no key here, with the guide's reason; so does a setting the guide has no row for |
| Left out on purpose | is something terragucci never does, such as an `import` workflow, with the guide's rule and what to do instead |

| Flag | Meaning |
|---|---|
| `--apply-when` | `pull-request` (the default, as Atlantis and OpenTaco apply before merge) or `merge`; a `digger.yml` whose `on_commit_to_default` runs `digger apply` already means `merge` |
| `--forge` | the forge, when the remote cannot tell; on GitLab the import keeps `apply.when: merge` and writes no `locks: plan`, and on Forgejo no `apply.merge: auto`, since those need a schedule or a token it cannot name |
| `--dry-run` | print what would be written, and write nothing |
| `--force` | replace an existing `terragucci.yml` |

It exits 2 when the file is missing or not YAML, or when `terragucci.yml` exists and `--force` is not given. A project `dir` that matches no directory with Terraform files is written and named.

Run [`init`](#init) next to write the pipeline.

`import terragrunt-scale` reads `.gruntwork` (or the directory named) and each unit's `gruntwork.hcl`, and writes each environment's plan and apply roles as `terragrunt.credentials` ([Terragrunt Scale](/terragucci/guides/use-terragrunt/#terragrunt-scale)). It exits 2 on a repo with no Terragrunt or a legacy `config.yml`.

`import spacelift` reads `.spacelift/config.yml` (or the file named) and every `spacelift_*` resource in the repo's `.tf` files; `import env0` reads `env0-discovery.yml` (or the file named), each `env0.yml` custom flow and every `env0_*` resource. Either runs on the admin code alone when the file is missing. They map by the concepts table of [Coming from Spacelift or env zero](/terragucci/guides/coming-from-spacelift-or-env-zero/#import), keep `apply.when: merge` unless `--apply-when` says otherwise, since both platforms apply a tracked branch after a push, and name each stack or environment whose state the platform manages.

### From a platform's workspaces

```bash
terragucci import hcp [--hostname <host>] --organization <org> [--repo owner/name] [--forge github|gitlab|forgejo] [--force] [--dry-run]
terragucci import otf --hostname <host> --organization <org> [--repo owner/name] [--forge github|gitlab|forgejo] [--force] [--dry-run]
terragucci import scalr --hostname <account>.scalr.io [--environment <name or ID>] [--repo owner/name] [--forge github|gitlab|forgejo] [--force] [--dry-run]
```

Reads the workspaces over the platform's API, with the token in `TF_TOKEN_<host>` or `credentials.tfrc.json` (for Scalr, also `SCALR_TOKEN`), and writes `terragucci.yml` and a `terraform.tfvars` in each root that has none, by [Coming from HCP Terraform, Scalr or OTF](/terragucci/guides/coming-from-hcp-terraform-scalr-or-otf/#import-the-workspaces). It only reads: no workspace, variable or run changes. A sensitive variable's value is never read; its name goes under `pass.secrets`.

| Flag | Meaning |
|---|---|
| `--hostname` | the platform's host; `app.terraform.io` for `hcp` when not given |
| `--organization` | the organization whose workspaces are read (`hcp`, `otf`) |
| `--environment` | one Scalr environment, by name or ID; every one the token sees when not given |
| `--repo` | this repo as the platform's VCS connection names it; the `origin` remote's `owner/name` when not given |
| `--forge` | the forge, when the remote cannot tell; on GitLab the secrets are listed as masked CI/CD variables to create, with no `pass` |
| `--dry-run`, `--force` | as above |

It exits 2 when the host refuses the token or names no TFE API, and, before it reads anything, when `terragucci.yml` exists and `--force` is not given.

## reconcile

```bash
terragucci reconcile [--config <file>] [--mode dry-run|apply] [--project <host/path>]
```

`--config` defaults to the config file in the working directory and `--mode` to `dry-run`. `--mode apply` opens a pull request per changed project and never runs `terraform apply` ([glossary](/terragucci/concepts/glossary/#words-that-mean-something-else-in-terraform)). `--project` limits the run to one project.

## generate

```bash
terragucci generate [--check] [--dry-run] [--config <file>]
```

From `terragucci.yml`'s `generate` key it writes `backend.tf`, `providers.tf` and `versions.tf` in each root and removes generated files the key no longer asks for. It never overwrites a file it did not write, and refuses a Terragrunt repo. `--dry-run` prints what it would write. `--check` writes nothing and fails on each generated file that differs from what it would write, is missing, or is no longer asked for, with the lines that differ. See [Generate backend and provider files](/terragucci/guides/generate-root-files/).

## estate

```bash
terragucci estate [--config <file>] [--out <dir>] [--link-hours <n>]
    [--bucket <url>] [--bucket-endpoint <url>] [--bucket-prefix <p>]
```

| Flag | Meaning |
|---|---|
| `--config` | the config file; default the one in the working directory |
| `--out` | where the page is written locally; default `terragucci-estate` |
| `--link-hours` | how long the link lives; default 24, at most 168 |
| `--bucket`, `--bucket-endpoint`, `--bucket-prefix` | the bucket to read and write (`s3://<bucket>`, `gs://<bucket>` or `az://<account>/<container>`), in place of `reports` in a repo's config |

| | `estate` |
|---|---|
| Reads | each project's `index.json`, `inventory.json`, `changes.json` and `states.json`; `audit.jsonl` and `audit.json` when the audit trail is there |
| Writes | `estate.html`, `estate.json` and `dora.json` at the top of the prefix; `history.html` and `history.json` once an apply changed a resource, with each apply's approver from `audit.jsonl` |
| Projects | in a control repo, its `projects:`, each read from its own `reports`, the page written to `defaults.reports`; in a repo of its own, the ones the top `index.json` lists |
| Also | links the audit trail when `audit.json` is beside the page; computes the [delivery metrics](/terragucci/reference/delivery-metrics/) and sends them as gauges when an OTLP endpoint is set |
| Exit 1 | a project's index could not be read; the page names it |

## audit

```bash
terragucci audit [--check] [--config <file>] [--out <dir>] [--link-hours <n>]
    [--bucket <url>] [--bucket-endpoint <url>] [--bucket-prefix <p>]
```

| Flag | Meaning |
|---|---|
| `--check` | build the entries again and compare them with the record; write nothing; exit code 1 naming each entry the record lacks |
| `--config` | the config file; default the one in the working directory |
| `--out` | where the record, page and summary are written locally; default `terragucci-audit` |
| `--link-hours` | how long the link to `audit.html` lives; default 24, at most 168 |
| `--bucket`, `--bucket-endpoint`, `--bucket-prefix` | the bucket to read and write, in place of `reports` in a repo's config |

| | `audit` |
|---|---|
| Reads | each project's `chant/lifecycle` history and its `tf-apply` wave reports |
| Writes | the entries `audit.jsonl` lacks, appended, and `audit.html` and `audit.json` beside it at the top of the prefix |
| Projects | in a control repo, its `projects:`, each ledger fetched from the project's repo and its reports read from its own `reports`, the record written to `defaults.reports`; in a repo of its own, the checkout's, its ledger read from `origin` |
| Exit 1 | a project's ledger or index could not be read, or with `--check` the record lacks an entry |

[The audit trail](/terragucci/reference/audit-trail/) describes every entry.

## plan and stage

```bash
terragucci plan [--root <glob>] [--project <host/path>] [--config <file>]
terragucci stage tf-plan [--root <glob>] [--project <host/path>] [--config <file>] [--out <dir>]
    [--report-url <url>] [--layers <a,b;c>] [--binary <b>] [--canary <globs>] [--bucket <url>]
    [--bucket-endpoint <url>] [--bucket-prefix <p>] [--bucket-url <url>] [--terragrunt] [--base <ref>] [--forge github|forgejo|gitlab] [--parallelism <n>] [--no-cost]
terragucci stage tf-drift [the same flags as tf-plan]
terragucci stage tf-apply --wave <n> --layers <a,b;c> [--canary <globs>] [--binary <b>]
    [--gate always|on-destructive|never] [--approval ledger|pr-review|sealed] [--config <file>] [--parallelism <n>] [--terragrunt [--rest]] [--base <ref>]
    [--shares <n> [--share <s>] [--decided <file>]] [--branches <branch>=<globs>[;...] [--branch <name>]]
    [--on-held wait|refuse] [--stand-down]
```

| Flag | Environment | Meaning |
|---|---|---|
| `--root` | | plan only the roots matching this glob |
| `--project` | | the project, as `<host>/<path>`, for a run from a control repo |
| `--config` | | the config file, when it is not at the repo root |
| `--out` | | where `stage` writes the report; default `terragucci-report/` |
| `--report-url` | | where the note links the HTML report; a URL that is not an `.html` file is read as the run's page |
| `--layers`, `--binary`, `--canary`, `--bucket` | | roots in apply order (layers split by `;`), binary, canary wave and bucket; each overrides `terragucci.yml` |
| `--bucket-endpoint`, `--bucket-prefix`, `--bucket-url` | | the store's endpoint, the key prefix, and the address that serves the bucket to a browser |
| `--terragrunt` | | run Terragrunt units, one `run --all` per wave; `tf-apply` applies each unit's saved plan |
| `--no-cost` | | leave out the cost estimate `cost` asks for; the confirm job passes it |
| `--rest` | | `tf-apply --terragrunt` only: run this wave, then each wave after it, stopping at the first that does not apply |
| `--base` | `TG_BASE` | the ref a change is measured against, such as `origin/main`; default is the pull request's target branch |
| `--forge` | | `github`, `forgejo` or `gitlab`, when the environment cannot tell; the plan note keeps to its comment limit, and `tf-drift` files its issue there |
| `--parallelism` | | roots run at once per dependency layer (`tf-plan`, `tf-drift`) or wave (`tf-apply`); overrides `parallelism` in `terragucci.yml`; `1` is serial |

Both `stage tf-plan` and `stage tf-drift` write the report even when a root refuses to plan. [The plan report](/terragucci/reference/report/) lists the files.

`stage tf-apply` applies one wave, as the generated `apply-wave-<n>` job does. Wave 1 first runs each [state migration](/terragucci/reference/migration-files/) that has not applied, behind its own gate, and `stage tf-plan` proves them. It refuses `--json` with exit 2. With `TG_OUTCOME_JSON` set it writes the wave's outcome to that file as [JSON](/terragucci/reference/cli-json/#the-apply-outcome).

| Flag | Environment | Meaning |
|---|---|---|
| `--wave` | | the wave to apply |
| `--gate` | | `always`, `on-destructive` (the default) or `never` |
| `--approval` | | the mode when the config at base names none and `chant.workspace.json` there lists no gate; a control repo's pipeline passes it |
| `--base` | `TG_BASE`, for the policy ref only | the ref that holds the wave's policy, approval mode, gate rule, signers file and other config; an open pull request's job passes `origin/<default branch>`. Without it the gate rule comes from the commit before the one applied |
| `--shares` | | `waves.jobs`: split the wave's roots into up to this many shares. Without `--share` the stage plans every root, decides the gate, writes each root's plan digest to `terragucci-wave/wave-<n>.json` and applies nothing |
| `--share` | | with `--shares`: plan this share's roots and apply them when each plan has the digest in the decision file; exit 4 when one moved |
| `--decided` | | the decision file, when it is not `terragucci-wave/wave-<n>.json` |
| `--branches` | | [`apply.branches`](/terragucci/reference/config/#apply-from-other-branches) as `release=envs/prod/*,envs/dr/*;staging=envs/staging/*`: the stage applies only the roots (in a Terragrunt repo, the units) of `--branch` when the map names it, and otherwise every root no branch's glob matches |
| `--branch` | | with `--branches`: the branch the push applies; unset means the default branch |
| `--on-held` | `TG_LOCK_POLL` | with `binary: choudoufu`, when another run's apply holds a resource the wave changes: `wait` (the default) polls every `TG_LOCK_POLL` seconds (10) for up to an hour, then plans again; `refuse` exits 5 naming that run, as the apply a comment starts does |
| `--stand-down` | | a push's wave: once it may apply, it applies nothing and exits 6 if a newer push is on its branch, which applies the whole tree |

## publish

```bash
terragucci publish [--dry-run] [--config <file>]
```

`--dry-run` lists what would be published and pushes nothing. A git tag that exists with the same content is unchanged and exits 0.

## verify-release

```bash
terragucci verify-release <module> <version> [--config <file>]
```

Run in the repo that publishes, with `modules.attest` set. For each target in `modules.publish` it reads the tag as it stands now and checks that the release ledger on `origin` records those bytes from the tag's commit. The public key must verify the release's signature, provenance and SBOM. It prints one line per target and exits 1 when any is refused.

## rollout

```bash
terragucci rollout <module> [<version>] [--from <version>] [--mode dry-run|apply] [--config <file>]
terragucci rollout --provider <address> <version> [--from <version>] [--mode dry-run|apply]
```

`--mode` defaults to `dry-run`, and neither mode runs `terraform apply`. See [Rolling out a module version](/terragucci/reference/stages/#rolling-out-a-module-version).

## respond

```bash
terragucci respond plan|wave-refused|apply-failed|drift|tips|fmt|publish|rollout|version-bump|description [--mode dry-run|apply] [flags]
terragucci respond rollout [--mode dry-run|apply]
```

`respond rollout` with a module runs that rollout's next step; without one it continues every rollout in flight and exits 1 only when one could not run.

| Flag | Used by | Meaning |
|---|---|---|
| `--mode` | all | `dry-run` (the default) or `apply`, which opens the pull request or pushes the commit and never runs `terraform apply` |
| `--report` | `plan`, `description`, `tips` | the report directory; for `tips`, a `stage tf-plan` report whose plans' renames get a `moved` block, and only those |
| `--approved`, `--current`, `--wave` | `wave-refused` | the approved report, the current report directory and the wave number |
| `--log` | `apply-failed` | the apply log; `-` reads standard input |
| `--root`, `--import` | `drift` | one root, and `<address>=<id>` for a resource the state does not hold |
| `--platform` | `tips` | lock file platforms, comma separated |
| `--branch` | `fmt`, `tips` | `fmt`: the branch to format; the default branch is refused. `tips` with `--report`: the branch the `moved` blocks' pull request goes into; default the default branch |
| `--module`, `--version` | `publish` | the module, and the release |
| `--module`, `--since` | `version-bump` | one module, and the ref to count changes from for a module with no release tag |
| `--title`, `--description` | `description` | the pull request's title and description; by default read from the job's event |
| `--attributions` | `drift` | the attributions `tf-drift` wrote, as a file; default `terragucci-report/attributions.json` |
| `--base` | `wave-refused`, `apply-failed` | read settings from the config at this ref (such as `origin/main`), not the checkout; an unreadable base gives no response and a logged reason |
| `--out`, `--binary`, `--config`, `--project` | all | as above |

[Responses to pipeline events](/terragucci/reference/responses/) explains each event. `respond` exits 0 once the event was handled, even when the response is `off`. The outcome is in the text, or in `results` with `--json` ([the JSON output](/terragucci/reference/cli-json/#respond)).

## comment

```text
terragucci comment --layers <a,b;c> --out <file> [--forge github|forgejo] [--agent off|on]
terragucci comment --agent run --out <file> --prompt <file> [--policy-dir <dir>] [--forge github|forgejo]
terragucci comment --agent push --change <dir> [--policy-dir <dir>]
terragucci comment --forge gitlab --poll --layers <a,b;c> [--when merge|pull-request] [--requires <list>|none] [--plan-notes]
```

Reads the pull request comment in the event file (`GITHUB_EVENT_PATH`) and writes a decision to `--out`: plan, or stop with a reason. A refused command is answered on the pull request. `--forge github` (the default) asks the API for the commenter's permission and `--forge forgejo` reads it from the event. The generated `replan` job runs it before any credential; see [Re-plan a pull request from a comment](/terragucci/guides/re-plan-from-a-comment/). `/terragucci apply` is read by `comment-apply`. Each `--agent` mode runs in its own job.

| `--agent` | Run by job | Does |
|---|---|---|
| `off` (the default) | `replan` | replies with how to turn the agent comment on |
| `on` | `replan` | leaves agent comments to the agent jobs |
| `run` | `agent` | decides on a `/terragucci agent <ask>` comment with the same checks and writes the prompt to `--prompt`; a fork or default-branch pull request gets no agent |
| `push` | `agent-push` | refuses the patch in `--change` when it touches a path an agent may not change, `--policy-dir` (default `policy`) among them, and commits a passing patch to the pull request's head branch with the `TG_*` variables in [Environment variables](/terragucci/reference/environment/) |

On GitLab, `--forge gitlab --poll` reads no event file; the generated `comments` job runs it on the comments schedule ([`comments`](/terragucci/reference/config/#keys)).

| Poll | Does |
|---|---|
| Which notes | those of the merge requests updated in the last day |
| Each `/terragucci` note | answered once: the reply carries a `<!-- terragucci:note=<id> -->` marker, and a note with one is never answered again |
| `--plan-notes` | first posts the plan note and status each merge request pipeline's plan job left in its report; the comments job passes it under `gitlab: { token: protected }` |
| Exit 1 | GitLab answered with an error |

| Note | Checked | Does |
|---|---|---|
| any | the author is a Developer or above; anyone else gets no reply | |
| `/terragucci plan [root]` | the merge request is open and from this project; a named root is a root of the pipeline | starts a merge request pipeline, which plans the whole merge request |
| `/terragucci apply` | the merge request merged into the default branch from this project; no later commit there has an apply of its own; no `wave-<n>` | retries the merge commit's first apply job that did not succeed; its gate decides again |
| `/terragucci apply [wave-<n>]`, with `--when pull-request` | the merge request is open, from this project, into the default branch; `--requires` (all four by default), `terragucci/plan` and the pipeline files, as `comment-apply` checks them | starts a pipeline on the default branch with `TG_MERGE_TOKEN` and the variables `TERRAGUCCI_MR`, `TERRAGUCCI_NOTE` and `TERRAGUCCI_HEAD` |
| `/terragucci lock`, `unlock`, with `--when pull-request` | the merge request is open | starts the same pipeline |
| `/terragucci lock`, `unlock` without it, `agent` | | replies that the verb does not run here |

[The generated pipeline](/terragucci/reference/pipeline/#the-agent-comment) lists the guarded paths, and [When a comment runs nothing](/terragucci/reference/pipeline/#ignored-comments) lists the checks every comment passes before a job uses a credential.

## review

```text
terragucci review prompt --report <dir> [--instructions <path>]
terragucci review post --dir <dir>
```

The `review` and `review-note` jobs of the generated review workflow run the two halves of the [review](/terragucci/guides/agent-review-a-pull-request/).

| Command | Does |
|---|---|
| `review prompt` | reads the pull request from the event file (on a `workflow_run` event, the one pull request of the run's head, with its title, description and base from the API); fetches the plan job's report from the pipeline's run of the head into `--report`, on a `pull_request_target` event waiting up to 30 minutes for the plan job; reads the diff of the base and head from git, and the plan note and policy results from the report; reads the instructions (`--instructions`, default `.terragucci/review.md`) from `origin/<default branch>` with `git show`, never from the checkout; writes the prompt to `/tmp/terragucci-review/prompt.md`, the pull request, head and base to `/tmp/terragucci-review/out/reviewed.json`, and unpacks the default branch's files into `/tmp/terragucci-review/work` |
| `review post` | reads the review and its command's exit code from `--dir` and posts them as one note on the pull request `TG_PR` names, with the head `TG_SHA` names; edits the note the pipeline posted before |

`review prompt` needs `TG_TOKEN`, a token that reads the repository's runs and artifacts. Exit 2 means the event names no pull request, a `workflow_run` event was not started by a `pull_request` run or names no one pull request of its head, or the checkout has no default branch ref. `review post` always exits 0 and says why when the forge refuses the note.

## pr-lock

```text
terragucci pr-lock --layers <a,b;c> [--forge github|forgejo] [--when merge|pull-request] [--terragrunt]
```

Reads the event file (a `pull_request_target` event, or a `/terragucci plan`, `lock` or `unlock` comment) and takes or releases the pull request's plan locks on `chant/lifecycle`. It posts `terragucci/lock` on the head and replies when another pull request holds a root. The generated `pr-lock` job runs it under [`locks: plan`](/terragucci/reference/config/#plan-locks). `--when pull-request` leaves `lock` and `unlock` to `comment-apply`; `--terragrunt` locks units.

## comment-apply

```text
terragucci comment-apply --layers <a,b;c> --out <file> [--canary <globs>] [--forge github|forgejo|gitlab]
    [--when merge|pull-request] [--requires <list>|none] [--terragrunt] [--again]
```

Reads a `/terragucci apply [wave-<n>]` comment, checks the commenter's permission as `comment` does, and writes a decision to `--out`: the merge commit and last wave to apply, or why nothing applies. The generated `apply-comment` job runs it before any credential. See [Apply a merged pull request](/terragucci/guides/re-plan-from-a-comment/#apply-a-merged-pull-request).

| `--when` | An open pull request |
|---|---|
| `merge` (the default) | does not apply |
| `pull-request` (written when `apply.when` is `pull-request`) | applies from its head once the checks in [Apply before merge](/terragucci/reference/pipeline/#apply-before-merge) pass; the command takes the root locks, `/terragucci lock` takes them without applying, and `/terragucci unlock` releases them |

`--requires` is a comma-separated list of `approved`, `mergeable`, `undiverged` and `checks`, or `none`; without it all four apply. `init` writes it from [`apply.requires`](/terragucci/reference/config/#apply-before-merge) when that leaves one out. `--terragrunt` (written in a Terragrunt repo under `apply.when: pull-request`) puts the locks on the units the pull request reaches, as [Locks](/terragucci/guides/apply-before-merge/#locks) describes. `--again` marks the second decision on Forgejo, which does not repeat a reply the first one posted.

The `mr-apply` job runs `--forge gitlab --when pull-request`, which reads no event file. `TERRAGUCCI_MR`, `TERRAGUCCI_NOTE` and `TERRAGUCCI_HEAD` name the merge request, note and head it reads from GitLab. Nothing runs unless the note is a Developer's `apply`, `lock` or `unlock` and the head is still the merge request's head.

## pr-merge

```text
terragucci pr-merge --pr <n> --sha <sha> [--forge github|forgejo|gitlab]
```

Merges the pull request while its head is still `--sha` and releases its root locks. The generated `pr-merge` job runs it after the last wave applied before merge, with `apply.merge: auto`. The sha comes from a job that ran the pull request's code, so the command first checks with `TG_TOKEN` that:

- the pull request is open;
- its head is `--sha`;
- a reviewer other than the author approved that head.

It merges with `TG_MERGE_TOKEN` if set (named by `apply.merge_token_env`), else `TG_TOKEN`.

With `--forge gitlab` it first looks for the `mr-apply` reply, from `TG_TOKEN`'s user, that says every wave of `--sha` applied in this pipeline (`CI_PIPELINE_ID`). Without one it exits 0 and prints `nothing to merge`. The approval it checks is one given after the merge request's latest push.

## plan-note

```text
terragucci plan-note --forge github|forgejo --report <dir> --plan-result <result> [--root <root>] [--approval-status]
```

| Flag | Meaning |
|---|---|
| `--forge` | `github` (the default) or `forgejo` |
| `--report` | the plan job's report directory, read as data; default `terragucci-report` |
| `--plan-result` | the plan job's result (`success` or `failure`), which `terragucci/plan` follows |
| `--root` | the root a `/terragucci plan <root>` re-plan named |
| `--approval-status` | also post `terragucci/approval`, under `approval: pr-review` |

The generated `plan-note` and `replan-note` jobs run it, and it always exits 0.

## approval-status

```text
terragucci approval-status [--forge github|forgejo] [--report <dir>]
```

Sets `terragucci/approval` on the head `TG_SHA` and `TG_PR` name. The status stays pending while a wave the gate will hold has no approving review of that head. With `--report` it reads the waves from that plan report; without it, from the head's plan note. Under `approval: pr-review` the generated `approval` job runs it on each review; it always exits 0.

## notify

```text
terragucci notify waiting|refused|failed --wave <n> [--outcome <file>] [--outcome-json <file>] [--report <dir>]
```

Sends one wave's outcome to whichever of `TERRAGUCCI_SLACK_WEBHOOK`, `TERRAGUCCI_TEAMS_WEBHOOK` and `TERRAGUCCI_WEBHOOK` are set. The generic webhook gets a [`terragucci.notify/v1`](/terragucci/reference/notify-event/) event signed with `TERRAGUCCI_WEBHOOK_KEY`, and nothing when the key is empty. With `notify` set, the generated apply jobs run it on any nonzero exit.

| Read from | For |
|---|---|
| `--outcome-json`, the stage's [outcome](/terragucci/reference/cli-json/#the-apply-outcome) (`TG_OUTCOME_JSON`) | the wave's roots, the digest and approve command of a waiting wave, the pull request to review under `approval: pr-review`, and the roots a refused or denied wave names |
| `--outcome`, the stage's `TG_OUTCOME` line | the outcome line the message quotes |
| `--report` (default `terragucci-report`) | the project, the report's link, and the wave's roots when there is no outcome |
| `GITHUB_SERVER_URL`, `GITHUB_REPOSITORY` and `GITHUB_RUN_ID`, or `CI_JOB_URL` | the run's link |
| `TERRAGUCCI_RELAY` | the relay a waiting wave's Approve and Decline buttons (Slack) and reply (Teams) reach |

```text
terragucci notify drift [--report <dir>]
```

Posts to `TERRAGUCCI_SLACK_WEBHOOK` and `TERRAGUCCI_TEAMS_WEBHOOK` the drift job's findings in `--report` (default `terragucci-report`): the roots found drifted and the roots that could not be refreshed. Its Re-plan button opens the page where a person reruns the drift check with their own login (the workflow's Run workflow page on GitHub and Forgejo; the pipeline schedules on GitLab). With no drift and every root refreshed it posts nothing. The generic webhook gets no drift event. The generated drift job runs it when `notify` names `slack` or `teams`.

A webhook that fails or does not answer within 10 seconds leaves a line in the log, and the command, which never prints a webhook's address, exits 0.

## relay

```text
terragucci relay [--port <n>]
```

Serves `POST /slack`, `POST /teams` and `GET /healthz`, with its settings from [the environment](/terragucci/reference/environment/#the-relay). On start it checks the token, and refuses one that can do more than approve. [Approve from Slack and Teams](/terragucci/guides/approve-from-chat/) sets it up.

| A request | The relay |
|---|---|
| whose signature does not verify, or a Slack one more than five minutes old | answers 401 and records nothing |
| from a chat user no line of the signers file on the default branch lists | answers in the thread that it refused, and records nothing |
| Approve, for the digest a wave waits for, under `approval: ledger` or `pr-review` | records the approval of that digest on `chant/lifecycle` as the person's principal, `relayedBy` the relay, and says so in the thread |
| Approve, for a digest no wave waits for | records nothing, and names the digest waiting |
| Approve, under `approval: sealed` | records nothing: only the approver's own key seals an approval |
| Decline | records nothing, and says in the thread who declined; the wave keeps waiting |

The relay runs until stopped, whatever error a request hits.

## query

```bash
terragucci query "<statement>" [--config <file>] [--json]
    [--bucket <url>] [--bucket-endpoint <url>] [--bucket-prefix <p>]
```

Loads the bucket's files into an in-memory SQLite database, runs the statement and prints the rows. It needs Node.js 22.13 or later. [Query the estate with SQL](/terragucci/guides/query-with-sql/) lists the tables.

| Flag | Meaning |
|---|---|
| `--config` | the config file; default the one in the working directory |
| `--bucket`, `--bucket-endpoint`, `--bucket-prefix` | the bucket to read, in place of `reports` in a repo's config |
| `--json` | the envelope, with `results.columns`, `results.rows` and `results.tables`, the row count of each table |

| | `query` |
|---|---|
| Reads | each project's `inventory.json`, `changes.json` and `edges.json`, and `audit.jsonl` |
| Projects | as `estate`: a control repo's `projects:`, with `audit.jsonl` from `defaults.reports`; otherwise the ones the top `index.json` lists |
| Refuses | a statement that does not begin with `SELECT`, `WITH` or `VALUES`, and any write |

## mcp

```text
terragucci mcp [--config <file>] [--bucket <url>] [--bucket-endpoint <url>] [--bucket-prefix <p>]
```

Serves the Model Context Protocol on stdin and stdout until the client closes them, for an agent that reads the estate while it works. It reads the reports bucket that `reports` names (or `--bucket` in a single repo) with credentials from its own environment ([Reports](/terragucci/reference/environment/#reports) lists the variables). [Read the estate over MCP](/terragucci/guides/agent-read-over-mcp/) connects a client.

| Tool | Reads | Arguments |
|---|---|---|
| `estate` | `estate.json`, as `terragucci estate` last wrote it | none |
| `index` | the report index rows, newest first, each with its `report` path | `project`, `stage`, `limit` |
| `report` | a run's `report.json`, or one root of it | `path`, `root` |
| `last_apply` | a root's newest `tf-apply` wave: its commit, wave, gate, whether it applied, its changes and the state version it left | `root`, `project` |
| `run_view` | the run view of one applied commit | `commit`, `project` |
| `state_versions` | `states.json`, the state versions each root's applies left | `root`, `project` |
| `audit` | the audit trail, `audit.jsonl`, newest first, with `audit.json` | `project`, `kind`, `limit` |
| `dora` | `dora.json` | none |
| `waiting` | the waves waiting on `chant/lifecycle` in the repo it runs in, each with the `terragucci approve` command a person runs | none |

Every tool is marked read-only, and the server refuses these calls.

| A call | The answer |
|---|---|
| to a tool it does not list, such as `approve`, `apply` or `override` | an error: the server is read-only, approvals belong to a person at a shell, and an approval made over MCP is refused |
| with an argument the tool does not list | an error naming the argument; one named like a credential (`token`, `secret`, `key`) says credentials come from the server's environment |
| with a `path` outside the reports prefix | an error |

The server writes nothing. Its bucket client refuses writes and signed links, and the server does not start with a tool whose name says it would write (approve, apply, override, lock, merge).

## view

```text
terragucci view [--reports <dir|s3://<bucket>/<prefix>|https://...>] [--project <host/path>]
    [--port <n>] [--no-open] [--export <dir> [--publish]] [--config <file>]
```

Starts [behold](https://intentius.io/behold/using/terragucci/) with `npx`, at the version this terragucci pins, on the repo's checkout and its reports bucket. It waits until behold answers on `http://127.0.0.1:<port>`, opens the browser, and runs until Ctrl-C. Each root is drawn as a box of its resources, and a resource a run flagged carries a mark with that run's finish time.

```bash
npx --yes -p @intentius/behold@0.25.0 -p @intentius/chant-lexicon-terraform@^0.121.0 -p @cdktn/hcl2json@^0.24.0 \
  behold serve <repo> --terragucci <reports> --terragucci-project <project> --port 4600
```

| Flag | Meaning |
|---|---|
| `--reports` | where to read the reports, in place of `reports` in the config: a directory, `s3://<bucket>/<prefix>` or an https address |
| `--project` | the project's name in the index; default the one a run in this checkout writes, from the git remote |
| `--port` | the port behold serves on; default 4600 |
| `--no-open` | serve without opening the browser |
| `--export` | write a static view to the directory instead of serving, without each root's source text |
| `--publish` | with `--export`, also upload the view to `<prefix>/views/behold/<commit>/` in the reports bucket, where no run writes; `<prefix>/views/behold/index.html` opens the newest commit, and the 30 newest are kept |
| `--config` | the config file; default the one in the working directory or at the repo's root |

| Reports in | behold reads |
|---|---|
| S3 | `s3://<bucket>/<prefix>`, with your shell's AWS credentials; `reports.endpoint` is passed as `AWS_ENDPOINT_URL_S3` |
| GCS or Azure Blob | `reports.url` with the prefix; with no `reports.url`, the command stops and asks for `--reports <dir>` with a copy made by `gcloud storage rsync` or `azcopy` |

`--publish` writes to S3 only. A read-only identity needs `s3:GetObject` on the prefix; `--publish` also needs `s3:PutObject`, `s3:GetObject` and `s3:DeleteObject` on `<prefix>/views/behold/*`: it reads the list of published commits and removes the files of a commit past the newest 30.

When behold stops, the command prints one line and exits 1:

| Cause | The line says |
|---|---|
| no `npx` | `npx` is not on the path |
| the repo's [`chant.workspace.json`](/terragucci/concepts/glossary/#chantworkspacejson) asks for a newer `minReader` than behold 0.25.0 reads | the repo asks for a newer reader than the pinned behold reads |
| the Terraform reader did not install | the package behold could not load |
| AWS refused or found no credentials | the source, and which error AWS gave |
| behold refused a report as malformed | behold's own error and what to fix |

The command writes nothing to the repo. behold refuses to deploy, approve or start a run on a terragucci repo, and a waiting wave shows the `terragucci approve` line to run in your shell.

## drift-agent

```text
terragucci drift-agent prompt --report <dir> --out <file> [--policy-dir <dir>]
terragucci drift-agent push --change <dir> [--forge github|forgejo] [--policy-dir <dir>]
```

Two generated jobs, `drift-agent` and `drift-agent-push`, run the halves of the [drift agent](/terragucci/guides/agent-fix-drift/).

| Command | Does |
|---|---|
| `drift-agent prompt` | reads `report.json` and `issue.json` from the drift job's report in `--report`, and writes the prompt to `--out`: each drifted resource with the state's value and the live one, never a sensitive one; exits 2 when the run opened no drift issue |
| `drift-agent push` | refuses the patch in `--change` when it touches a path an agent may not change, `--policy-dir` (default `policy`) among them; commits a passing patch on top of `TG_SHA` to `terragucci/drift-agent-<issue>`, pushes it without force with `TG_TOKEN`, opens the pull request and comments its link on the issue `TG_ISSUE` names |

## config check

```bash
terragucci config check [--config <file>]
```

Lists every problem. [The config keys](/terragucci/reference/config/) names the files it reads. A repo with [migration files](/terragucci/reference/migration-files/) is also a problem when its generated GitHub pipeline has an apply job that may not write `chant/lifecycle`; the message names the jobs and `terragucci init`, which writes the pipeline again.

```text
terragucci.yml: ok
approval: ledger (the default)
```

With [`oidc.roles`](/terragucci/reference/pipeline/#credentials) in a repo of plain roots, it reads each root's backend and `terraform_remote_state` blocks and prints a line per role and stage with the state that role reaches. Every glob in `oidc.roles` is an environment, and the unmatched roots form one more under `plan_role` and `apply_role`. `oidc.gcp.roles` and `oidc.azure.roles` get the same lines and warnings, marked `gcp` or `azure`, for the `gcs` or `azurerm` states their roots keep. Each warning goes to stderr.

| Warning | When |
|---|---|
| a role is the role of two environments | the same role ARN in two globs, or a glob and the pair; it reaches the state of each |
| a root reads the state of another environment's root | its `terraform_remote_state` names that root's state key, so its roles must reach that state |
| a root matches no glob and `oidc` names no pair | the root plans and applies with no AWS role |

Under `terragrunt.credentials` it warns when one role serves two unit globs.

In a repo of plain roots it warns for each `terraform_remote_state` block whose state [address](/terragucci/guides/track-cross-state-edges/#state-addresses) is not plain strings in the code, and, when any root reads state, for each root whose own backend's address is not. No edge orders those roots.

```text
terragucci.yml: 1 warning(s)
  state: app reads state through terraform_remote_state "net" where the code does not say (its pg conn_str is an expression, not a plain string), so it is not ordered after the root that writes it
```

Warnings leave the exit code 0.

```text
terragucci.yml: ok
approval: ledger (the default)
state access:
  arn:aws:iam::444455556666:role/dev-plan (plan, envs/dev/**): s3://acme-state/dev/app.tfstate
  arn:aws:iam::444455556666:role/dev-apply (apply, envs/dev/**): s3://acme-state/dev/app.tfstate
  arn:aws:iam::111122223333:role/prod-plan (plan, envs/prod/**): s3://acme-state/prod/app.tfstate; reads s3://acme-state/dev/app.tfstate
  arn:aws:iam::111122223333:role/prod-apply (apply, envs/prod/**): s3://acme-state/prod/app.tfstate; reads s3://acme-state/dev/app.tfstate
terragucci.yml: 1 warning(s)
  oidc: envs/prod/app (envs/prod/**) reads the state of envs/dev/app (envs/dev/**) through terraform_remote_state, so arn:aws:iam::111122223333:role/prod-plan and arn:aws:iam::111122223333:role/prod-apply reach s3://acme-state/dev/app.tfstate, another environment's state
```

## approve

```bash
terragucci approve [wave-<k> | <migration>] [--plan <digest>] [--actor <name>] [--sign [<key>]] [--dry-run] [--no-resume]
terragucci approve export <root> --plan <digest> [--sign]
terragucci approve unlock <root> --plan <digest> [--sign]
terragucci approve ephemeral <pr> --plan <digest> [--sign]
```

| Flag | Meaning |
|---|---|
| `wave-<k>` | the wave to approve; needed only when several wait and no `--plan` picks one |
| `<migration>` | a [state migration](/terragucci/reference/migration-files/) wave 1 waits on, by name: it approves the migration's digest and resumes wave 1; needed only when another gate waits too and no `--plan` picks one |
| `--plan` | the digest you read, from a chat message, a plan note or a report: approve only a wave waiting for exactly that digest. When none does, it approves nothing, prints the digest waiting and exits 1 |
| `--actor` | the name the approval records; under `approval: sealed`, your principal in the signers file |
| `--sign` | seal the approval with this key, or with git's `user.signingkey` when no key is given; the default under `approval: sealed` |
| `export <root>` | a [state export](#state-export) request for `<root>`; it counts only from someone other than the person who asked |
| `unlock <root>` | the release of the lock [`unlock-state`](#unlock-state) found on `<root>` |
| `ephemeral <pr>` | pull request `<pr>`'s [ephemeral environment](#ephemeral) |
| `--dry-run` | print what it would approve and record nothing |
| `--no-resume` | record the approval only; by default it then starts the wave again with your forge token ([Resume after an approval](/terragucci/reference/pipeline/#resume-after-an-approval)) |

Run it in a checkout whose `origin` you can push to.

```text
wave-2 waits for an approval of jcs1-sha256:2e7a63f3... (wave 2 of 2: app), since 2026-10-07T18:04:11.000Z
  roots: app
  destroys app: aws_s3_bucket.logs
```

With a digest that no longer waits, because the plans moved after you read them, `terragucci approve wave-2 --plan jcs1-sha256:9f2c...` prints:

```text
not approved: wave-2 waits for jcs1-sha256:9f2c...; waiting: wave-2 for jcs1-sha256:2e7a63f3.... The plans moved since that digest, or were approved and applied; read the waiting plans, then approve their digest
```

## migrate

```bash
terragucci migrate revert <migration>
```

Writes `migrations/<migration>-revert.yml`, the [revert](/terragucci/reference/migration-files/#revert) of a migration that applied, from its record on `chant/lifecycle` as `origin` holds it. Nothing else is written; the plan job proves the change that carries the file, which waits at wave 1 for its approval like any migration. Exit code 1 when the migration never applied, moved states to a new backend, or left a root with no version to put back.

## state export

```bash
terragucci state export <root> [--version <id>] [--out <file>] [--actor <name>]
```

| Flag | Meaning |
|---|---|
| `<root>` | the root whose state to export, with a backend that keeps versions (an `s3` bucket with versioning, a `gcs` bucket with object versioning, an `azurerm` account with blob versioning or a backend with `snapshot = true`), or on GitLab-managed state: a plain root, or a Terragrunt unit, which Terragrunt prepares through its `remote_state` block |
| `--version` | the version id, as the estate page's State versions section lists it (GitLab's serial on GitLab-managed state); the current version by default |
| `--out` | where to write the file, outside the repo; a new private directory under the system's temp directory by default |
| `--actor` | who asks; git's `user.name` by default |

Run it twice in a checkout whose `origin` you can push to, signed in to the cloud as yourself. [Export a state version](/terragucci/guides/export-a-state-version/) has the steps.

| Run | Does | Exits |
|---|---|---|
| first | reads the version's metadata, records a request on `chant/lifecycle` and prints `terragucci approve export <root> --plan <digest>` for someone else to run | 3 |
| second, once that approval stands | downloads the version, records the export in `_gates/tf-state-export/done.jsonl`, then writes the file, readable by you alone | 0 |

```text
state export: wrote /tmp/terragucci-export-Xb3k/envs_dev_app.3HL4kqtJlcpXroDTDmJ.rmSpXd3dIbrHY.tfstate: envs/dev/app's state, s3://acme-state/dev/app.tfstate version 3HL4kqtJlcpXroDTDmJ.rmSpXd3dIbrHY, approved by bob
```

An approval by the person who asked does not count. A request exports once; another export asks again. It never writes a state to the reports bucket or a job artifact.

## unlock-state

```bash
terragucci unlock-state <root> [--actor <name>] [--binary <b>] [--config <file>]
```

Releases the state lock a job killed mid-apply left on `<root>`: the lock file an `s3` backend with `use_lockfile = true` takes, a `gcs` backend's lock object, an `azurerm` backend's lease on the state blob, or the lock of GitLab-managed state. A comment never runs it. Run it at a shell with:

- the backend's credentials;
- the forge token in the variable `token_env` names (by default `FORGEJO_TOKEN`, `GITHUB_TOKEN` or `GITLAB_TOKEN`);
- push access to the checkout's `origin`.

| Step | Does |
|---|---|
| read the lock | inits the root and reads the lock file, the gcs lock object or the azurerm lease and metadata, or asks GitLab's lock endpoint: its ID, who took it and when |
| check no holder is alive | reads the forge's runs still running or waiting; while one that began before the lock was taken is alive, it may hold the lock, so nothing is released and it exits 1 naming the runs. A forge it cannot read is a refusal too |
| wait at the gate | records a pending fact for gate `<root>` of op `tf-unlock` on `chant/lifecycle`, bound to a digest of the root, the lock's location and its ID, prints `terragucci approve unlock <root> --plan <digest>` and exits 3. Under `approval: sealed`, only a sealed approval counts |
| release | approved, it checks the runs again, runs the binary's `force-unlock` of that ID (on GitLab, a `DELETE` of that ID on the lock endpoint), and appends who released which lock, and under whose approval, to `_gates/tf-unlock/done.jsonl`, which the [audit trail](/terragucci/reference/audit-trail/) reads |

| Flag | Meaning |
|---|---|
| `--actor` | the name the record gives the person who released it; default git's `user.name` |
| `--binary`, `--config` | as above |

```text
terragucci unlock-state: slow: s3://acme-state/slow.tfstate.tflock holds lock 1f0c..., OperationTypeApply by root@runner-7 at 2026-10-09T18:02:11.420Z
terragucci unlock-state: slow: no run that began before the lock is alive
terragucci unlock-state: slow: releasing lock 1f0c..., OperationTypeApply by root@runner-7 at 2026-10-09T18:02:11.420Z waits for an approval of digest jcs1-sha256:6d2b.... Approve it with:
terragucci unlock-state:   terragucci approve unlock slow --plan jcs1-sha256:6d2b...
```

An approval names one lock. If that lock was released some other way and a new one taken, the approval does not release the new one and the command exits 4.

## ephemeral

```bash
terragucci ephemeral up --pr <n> [--head <sha>] [--base <ref>] [--binary <b>] [--config <file>]
terragucci ephemeral down --pr <n> --reason closed|expired [--base <ref>] [--binary <b>] [--config <file>]
terragucci ephemeral sweep [--base <ref>] [--binary <b>] [--config <file>]
```

The generated pipeline runs it for [`ephemeral`](/terragucci/reference/config/#ephemeral-environments). It reads `ephemeral` from the checkout's terragucci.yml (the default branch, or `--base`) and checks out the pull request's code separately from the forge's pull request ref.

| Subcommand | What it does |
|---|---|
| `up` | inits each root the globs match at `--head` with `-backend-config` naming its key with `-pr-<n>` added, plans it, and decides gate `pr-<n>` of op `tf-ephemeral` on the set digest as `gate` says, printing `terragucci approve ephemeral <n> --plan <digest>` and exiting 3 while it waits; then applies, and appends the copy, its expiry and who approved it to `_gates/tf-ephemeral/done.jsonl` |
| `down` | plans the destroy of each root of the live copy and applies it, in reverse order, from the commit the copy applied, and appends the destroy with `--reason` and its digest; with no live copy it does nothing |
| `sweep` | destroys each live copy whose TTL passed (`expired`), and each whose pull request the forge says is closed or merged (`closed`), reading it with `TG_TOKEN` |

These are config errors (exit 2):

- a root on a backend other than `s3`, `azurerm`, `gcs` or `local`;
- a backend block that names no key;
- a Terragrunt repo;
- `synth`.

A destroy that fails leaves the copy live, and the next sweep tries again.

## resume

```text
terragucci resume [--forge github|forgejo|gitlab] [--out <file>]
```

The resume job runs it ([Resume after an approval](/terragucci/reference/pipeline/#resume-after-an-approval)). From `chant/lifecycle` it finds each waiting wave, and each state migration wave 1 waits on, whose digest has an approval no apply has used. An approved migration resumes wave 1, which runs it. It also finds a wave whose approved choudoufu apply was killed, once that run is gone ([Stopped applies](/terragucci/reference/pipeline/#stopped-applies)). It writes `TG_SHA` and `TG_PR` to `--out` for the job's waves to apply on GitHub and Forgejo, and retries the waiting apply job on GitLab. It exits 0 when there is nothing to resume.

## override

```bash
terragucci override <root> --rule <id> [--rule <id>] --reason <text> [--actor <name>] [--sign [<key>]] [--dry-run]
```

| Flag | Meaning |
|---|---|
| `<root>` | the root the policy denied |
| `--rule` | a rule that denied it, such as `main.deny_public_bucket`; name every one, or give them comma-separated |
| `--reason` | required: why this plan goes out, kept on the ledger and shown in the report |
| `--actor` | the name the override records; it counts only when [`policy.override`](/terragucci/reference/policy/#overriding-a-denial) at base lists it |
| `--sign` | as for `approve`; the default under `approval: sealed` |
| `--dry-run` | print what it would override and record nothing |

```text
envs/prod/app: its plan jcs1-sha256:4c1e09d2... was denied by main.deny_public_bucket, since 2026-10-07T18:04:11.000Z
  the override binds the root, that plan and those rules: sha256:9b0f2a71...
```

## check-root, check-pins and check-policy

```bash
terragucci check-root <dir> [--binary <b>] [--config <file>] [--base <ref>]
terragucci check-pins [--config <file>] [--base <ref>]
terragucci check-policy [--config <file>] [--base <ref>]
```

| Command | Does |
|---|---|
| `check-root` | runs `validate -json` in an initialised root and prints each diagnostic with its file and range; with `--binary choudoufu`, also `choudoufu live-check -json`. Under `modules.require: attested` (read at `--base`) it first checks the root's module pins |
| `check-pins` | the same pin check on each Terragrunt unit's `terraform { source }`; prints nothing without `modules.require: attested` |
| `check-policy` | runs the policy's tests when `policy` is set |

Each appends to `terragucci-check/report.md`, and the generated `tf-check` job runs all three. See [Stages](/terragucci/reference/stages/#check).

## install

```bash
terragucci install tofu|terraform|terragrunt|choudoufu|infracost|cosign|atmos|terramate <version>
```

Prints the directory it unpacked the release to, after checking it against its SHA256SUMS. The releases are Linux builds. Under `modules.attest` the publish job installs cosign this way before it publishes; in an Atmos repo every job installs Atmos this way.

## --json

`init`, `reconcile`, `plan`, `stage`, `rollout`, `respond`, `config check` and `query` take `--json`, which makes the command print only one envelope on stdout. [The CLI's JSON output](/terragucci/reference/cli-json/) lists the fields.

## Exit codes

The codes are the same with or without `--json`. Every command exits 2 on a usage or config error.

| Code | Meaning |
|---|---|
| 0 | done |
| 1 | one or more projects or roots failed |
| 2 | a usage or config error |
| 3 | waiting on an approval, or on a rollout's pull request |
| 4 | a wave's plans changed after an approval or a policy override no run applied, or a share's plans changed after its wave decided, so `stage tf-apply` applied nothing |

| Command | 0 | 1 | 2 | 3 | 4 |
|---|---|---|---|---|---|
| `init` | done | | an existing config file needs a line added | | |
| `reconcile` | done | a project failed | | | |
| `generate` | written, or with `--check` every generated file matches | with `--check`, a generated file out of line | a file it did not write is in the way, or a root's own files declare what it would write | | |
| `plan`, `stage tf-plan`, `stage tf-drift` | done | a root refused to plan | | | |
| `stage tf-apply` | wave applied, or with `--shares` decided for its shares | a root failed, or the policy denied one | `--json`, or a share with no decision file | waits for an approval | plans changed after an approval or a policy override no run applied, or after a share's wave decided |
| `publish` | done | | OCI tag exists already; git tag exists with different content | | |
| `rollout` | complete | stopped | | waiting | |
| `respond` | event handled, even when the response is `off` | | unknown event or missing flag | | |
| `comment`, `comment-apply` | decision written, or every note answered | forge error, unreadable event file | | | |
| `pr-lock` | locks taken, refused or released | the locks could not be read or pushed, unreadable event file | | | |
| `pr-merge` | merged | not merged | | | |
| `config check` | `ok`, with or without warnings | | problems found | | |
| `state export` | the version written and recorded | | a root, backend or version it does not export, a file inside the repo, or nobody named | waits for an approval by someone else | |
| `check-root`, `check-pins`, `check-policy` | passed | failed | | | |
| `install` | done | | not a Linux host | | |
| `estate` | page written | a project's index could not be read | | | |
| `audit` | record written, or with `--check` nothing missing | a ledger or index could not be read; with `--check`, an entry the record lacks | | | |
| `verify-release` | every target verified | a target refused | | | |
| `ephemeral` | applied, destroyed, or nothing to do | a root failed to plan, apply or destroy | no `ephemeral` roots, a backend no key suffix fits, a Terragrunt unit whose `remote_state` key does not read `TERRAGUCCI_EPHEMERAL_SUFFIX` | the copy waits for an approval | an approval stands for other plans of the copy |
| `unlock-state` | released, or no lock held | a run that may hold the lock is alive | no forge token, a forge it cannot read, a backend with no lock file | waits for an approval of the lock | an approval stands for another lock |
| `approve`, `override` | approved | `approve --plan` names a digest no wave waits for | no wave waiting, several waiting and none named, no recorded denial, or the rules differ | | |
| `resume`, `notify`, `plan-note`, `approval-status` | always, once the flags parse | | a bad flag | | |
| `relay` | never: it serves until stopped | | a missing setting, a token that can do more than approve, or a repo it cannot read | | |
| `query` | rows printed | | a bad flag or config, a statement that does not run or writes | | |
| `mcp` | the client closed stdin | | a bad flag or config | | |
| `view` | stopped with Ctrl-C, or the view exported | behold stopped or refused the reports | a bad flag or config, or a source behold cannot read | | |
| `drift-agent` | prompt written; pull request opened, or the change refused with a comment on the issue | git or the forge failed | a bad flag, or a run that opened no drift issue | | |

Code 4 comes from `stage tf-apply`, `unlock-state` and `ephemeral`, which have no `--json`.

---

# Stages

Source: https://intentius.io/terragucci/reference/stages/

Every stage takes the root directories and the binary.

| Stage | What it does | Forge permissions | Outputs |
|---|---|---|---|
| `tf-check` | format, `validate`, and with [`choudoufu`](/terragucci/concepts/glossary/#choudoufu) a [live check](#check) that needs no cloud credentials; with [`policy`](/terragucci/reference/policy/) set, the policy's own tests | read the repository, with no forge token; when a branch's check fails, a separate `fmt` job pushes the formatting commit (`respond.fmt: commit`, the default; in a Terragrunt repo it runs `terragrunt hcl fmt` too; not with `gitlab.token: protected`) | pass or fail, the log, and the check report |
| `tf-plan` | plans the affected roots in one run and posts the grouped summary; with [`policy`](/terragucci/reference/policy/) set, fails a denied root | read the repository, comment on pull requests | the grouped summary, and a plan digest per root |
| `tf-apply` | applies one job per wave; a wave the [gate policy](#gate-policy) holds (under the default `on-destructive`, one that destroys or replaces) waits for an approval; with [`policy`](/terragucci/reference/policy/) set, refuses a denied wave | read the repository, write the [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) branch (read only under `gate: never`), post statuses and pull request comments; with `waves.jobs`, push the run's shared lock tag | per wave, whether it waited and its approval command |
| `tf-drift` | plans every root `-refresh-only` on a schedule and groups what changed outside Terraform | read the repository, write issues | the plan report, and one drift issue |
| `tf-publish` | publishes each changed module as an OCI artifact or a git tag | read the repository, push tags or to the registry | the new version and its digest |
| `tf-rollout` | opens one pull request per wave, moving the pin for that wave's roots | open pull requests, in every project of the wave | per wave, its pull requests and their state |

## Exit codes

Stages exit with [the CLI's codes](/terragucci/reference/cli/#exit-codes). Two belong to waves:

| Code | Means |
|---|---|
| 3 | a wave waits for approval |
| 4 | a wave's plans changed after an approval no run applied, so nothing applied |

## Check

`tf-check` runs on every push and fork pull request, once per root. A failing root does not stop the next, so one run shows every diagnostic. Warnings print and fail nothing. Under [`modules.require: attested`](/terragucci/guides/publish-modules/#require-attested-releases), a root whose module pins do not verify fails before `validate`, and `tf-plan` fails it before `init`.

**Terraform**

| Order | Command | A difference |
|---|---|---|
| 1 | `terraform fmt -check` | stops the job |
| 2 | `terraform init -backend=false` | fails the root |
| 3 | `terraform validate -json` | fails the root |
**OpenTofu**

| Order | Command | A difference |
|---|---|---|
| 1 | `tofu fmt -check` | stops the job |
| 2 | `tofu init -backend=false` | fails the root |
| 3 | `tofu validate -json` | fails the root |
**Terragrunt**

| Order | Command |
|---|---|
| 1 | the binary's `fmt -check -recursive -diff .` |
| 2 | `terragrunt hcl fmt --check` |
| 3 | `terragrunt hcl validate --inputs` |
**choudoufu**

:::tip[A live check before any plan]
Every pull request learns, before any plan and with no cloud credentials, whether each resource can carry the tag that identifies it.

<small>The <a href="/terragucci/guides/use-a-binary/#choudoufu">choudoufu binary</a> (the OpenTofu fork from the team behind terragucci) runs this check.</small>
:::

| Order | Command | A difference |
|---|---|---|
| 1 | `fmt -check` | stops the job |
| 2 | `init -backend=false` | fails the root |
| 3 | `validate -json` | fails the root |
| 4 | `choudoufu live-check -json`, no cloud calls | each refusal prints its rule, reason, resource types and sites; a non-zero exit fails the check |

A failed validate prints the file, line and error:

```text
error: envs/dev/orders/main.tf:12:3-12:8: Unsupported argument
    An argument named "bogus" is not expected here.
FAILED envs/dev/orders: validate found 1 error(s)
```

With [`generate`](/terragucci/guides/generate-root-files/) set, the check job also runs `terragucci generate --check` before the roots' `init`, and fails on a generated file that differs from what `terragucci generate` writes:

```text
refused: envs/prod/app/backend.tf differs from what terragucci generate writes from terragucci.yml:
    -    bucket = "hand-edited"
    +    bucket = "acme-prod-state"
FAILED generate: 1 generated file out of line with terragucci.yml; run terragucci generate and commit what it writes
```

When [`policy`](/terragucci/reference/policy/) is set, the last step runs `conftest verify` or `opa test`, with the tests and key read from the default branch or the pull request's target. The log is kept as `terragucci-check/report.md`.

## Drift

A cron schedule in `drift` adds a `drift` job that runs on it.

```yaml
drift: "0 6 * * *"
```

| Drift job | What it does |
|---|---|
| Plans | each root with `-refresh-only`, so merged but unapplied code is not drift; a Terragrunt repo runs one refresh-only `terragrunt run --all` per wave. A choudoufu root under live resource markers plans in full, and what its plan would change is the drift ([Live roots](/terragucci/guides/turn-on-drift-checks/#live-roots)) |
| Identity | with `oidc`, the plan job's read-only role; it never applies |
| Fails | when a root cannot be refreshed; drift alone does not fail it |
| Report | stage `tf-drift` ([the report](/terragucci/reference/report/)), kept as an artifact |
| Issue | at most one open per project, titled `terragucci: drift found`, below |
| By hand | `npx terragucci stage tf-drift`; with no forge token it writes the report and `issue.md` only, and `--forge` tells GitHub from Forgejo |

| This run finds | The issue |
|---|---|
| drift, and none is open | opens, with each drifted root and what moved in it |
| drift, and one is open | updates in place, so the issue always shows the latest run |
| no drift in any root | closes, with a comment naming the commit |
| no drift, but a root could not be planned | stays as it is, since that root is unknown |

| Forge | Issue token | Schedule |
|---|---|---|
| GitHub, Forgejo | the job's own, `issues: write` | the workflow, plus `workflow_dispatch` with no `pr` |
| GitLab | `token_env`, `api` scope | CI/CD > Schedules, by hand |

### Overdue drift checks

A schedule can stop with no error: GitHub turns a scheduled workflow off after 60 days with no activity in the repo, and a GitLab project runs the drift job only once someone adds a schedule. With `drift` set, each `tf-plan` checks:

1. The plan job asks the forge when the drift job last ran (scheduled or by hand).

2. It counts how often the cron has come round since then (or since the pipeline file was added, if the job never ran).

3. At two or more, the job log and plan note warn that the drift checks are overdue and say what to do.

| Forge | What the plan job reads | The note adds |
|---|---|---|
| GitHub | the workflow's scheduled and manual runs, and its state; the plan jobs get `actions: read` | the workflow is off, or how to turn it on again |
| GitLab | the scheduled pipelines and the active schedules, with `token_env` | the project has no schedule, and the cron to add |
| Forgejo | the repo's scheduled and manual runs | to check that Actions is on and a runner is up |

A forge that does not answer leaves a line in the log, and the plan goes on.

## Gated waves

A wave the [gate policy](#gate-policy) holds waits for an approval bound to its set digest, and a changed plan stops it. See [Approve a waiting wave](/terragucci/guides/approve-a-wave/).

A waiting wave prints its set digest and approval command.

## State migrations

A file in `migrations/` moves resources between roots' states. `stage tf-plan` proves the first migration not yet applied (a later one plans against the states it writes): every affected root must plan with no change against its new state, or the job fails. Wave 1 of `stage tf-apply` proves it again before planning its roots and waits on the gate `tf-migrate <name>`. An approval lets it write the new states under each state's lock and record each version before and after.

| Exit code | Means |
|---|---|
| 3 | the migration waits on its gate |
| 4 | a state moved since the approval |
| 1 | the migration cannot be proved or written |

See [Move resources between roots](/terragucci/guides/move-resources-between-roots/) and [Migration files](/terragucci/reference/migration-files/).

## Rolling out a module version

How a root takes a module decides how a new version reaches it.

| The root's module source | Roots a change reaches | How it goes out |
|---|---|---|
| a local path, `../modules/x` | every root that includes it | one change set, applied in gated waves |
| an exact pin: an `oci://` tag or digest, a registry `version`, a git tag | only those whose pin moved | `tf-rollout`, one pull request per wave |
| a range such as `~> 1.4` | cannot be told from the diff | neither; terragucci refuses it and tips you to pin it |
| a provider version, in `.terraform.lock.hcl` | everything using the provider | `tf-rollout`, moving the lock file a wave at a time |

```bash
terragucci rollout modules/network                 # dry run: the newest published version
terragucci rollout modules/network 1.4.0 --mode apply
terragucci rollout --provider hashicorp/aws 6.68.0 --mode apply
```

No version means the newest published tag; `--from` picks between disagreeing pins. Each run takes one step; `--mode apply` opens pull requests with `token_env`; it never applies or merges and never writes a default branch. With [`rollouts`](/terragucci/reference/config/) set, a scheduled job takes the next step for you.

| Exit code | Meaning |
|---|---|
| 0 | a step was taken, or the rollout is at its end |
| 3 | a pull request waits for a merge or an apply |
| 1 | the rollout stopped, after a closed pull request or a failed apply |

[Roll out a new module version](/terragucci/guides/roll-out-a-module-version/) walks through a rollout.

A pin the rollout cannot move is reported with its reason and a tip:

| The pin | Tip |
|---|---|
| a range such as `~> 1.4` | `rollout-floating-pin`: pin one version |
| set from a variable or a local | `rollout-literal-pin`: write a literal, since a variable's value is not in the diff |
| absent from the source | `rollout-pin`: add a `?ref=`, `?tag=` or `version` |
| two versions of the module in one directory | `rollout-one-pin`: pin every call at one version |
| a provider with no `.terraform.lock.hcl` | `rollout-lock-file`: commit the lock file |

A provider rollout rewrites each lock file, and any exact `version` constraint, for that provider alone; any other change stops the wave.

Reading module pins needs `npm i -D @cdktn/hcl2json`.

## Publishing modules

`modules.path` names the modules; `modules.publish` takes an `oci://` address, `git-tags`, or both.

| Binary | Roots pin |
|---|---|
| OpenTofu | `oci://` sources |
| Terraform | git tags such as `modules/network/v1.4.0` |

```bash
terragucci publish --dry-run
terragucci publish
```

The `publish` job runs after `apply` on the default branch and alone gets the [registry credentials](/terragucci/reference/environment/). With `modules.attest` it also signs each release and records it in the release ledger on `chant/lifecycle`. See [Publish your modules](/terragucci/guides/publish-modules/).

### Version bump rules

A changed module is published at the version these rules give, which the [version-bump response](/terragucci/reference/responses/#version-bump) also uses.

| Commit or file | Bump |
|---|---|
| `feat` | minor |
| `feat!:` or `BREAKING CHANGE:` | major |
| any other conventional commit | patch |
| no conventional commit, with `respond.version-bump: suggest` | the typed-decision service picks; patch below its threshold or without it |
| a `version` file in the module | overrides all of the above |
| no earlier release | `0.1.0` |

## The grouped summary

The plan and drift stages group identical changes and name each destroy, replacement or refusal. See [the plan report](/terragucci/reference/report/).

## Gate policy

`tf-apply` takes one of three policies for each wave.

| Policy | Waits for an approval when |
|---|---|
| `always` | the wave has at least one change; a wave whose plans change nothing never waits |
| `on-destructive` | the wave's plans destroy or replace something |
| `never` | never; only pull request review and default-branch protection stand before the apply |

`on-destroy` is an older name for `on-destructive`, and `terragucci.yml` and `--gate` still accept it, so a pipeline rendered with it keeps working. SQL Yodeler and chant's Op waves call the same policy `on-destructive`.

Run the approval command a waiting wave prints and run the stage again.

---

# Report JSON schema

Source: https://intentius.io/terragucci/reference/report-schema/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/reference/report-schema/.
Write a jq script that reads terragucci-report/report.json and prints every destroy and replacement by address, with its root and the wave that applies it.
Read only. Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

`report.json` sits beside every `report.html`, which also carries it inline:

```bash
sed -n '/id="terragucci-report"/,/<\/script>/p' report.html | sed '1d;$d' | jq '.named[] | select(.action == "delete") | .address'
```

## Fields

| Field | Holds |
|---|---|
| `schema` | `terragucci.report/v1`; a minor version only adds fields |
| `minor` | the minor version of the schema the report was written with |
| `run` | project, commit, base, stage, binary, runtime, start and finish times, and the job |
| `run.wave`, `run.terragucci` | the wave a `tf-apply` report is for, and the terragucci version that wrote the report |
| `run.share` | on a `tf-apply` wave split across jobs (`waves.jobs`), the share the report applied; its `waves[0].roots` are the share's roots |
| `run.commit_url`, `run.pull_request`, `run.pull_request_url` | the commit's page, and the pull or merge request the run planned with its page |
| `run.report_url` | where this `report.html` is served from the bucket, when `reports.url` is set |
| `run.trace_id`, `run.trace_url` | the run's trace, when the stage sent one, and its link when `telemetry.trace_url` is set |
| `change_set` | the set digest over every root's plan digest, the digest an approval names |
| `unit`, `units` | what the groups count: `member` or `instance`, and how many |
| `groups[]` | a stable id per normalized change, its roots and the change |
| `totals` | the run's changes by action, over the roots whose plan can apply; a root the policy denied is left out, though its `changes` stay in the report. GitLab's `reports:terraform` counts come from it |
| `roots[]` | path, plan digest, counts by action, its group, its changes and why it is open |
| `waves[]` | one entry per wave; [its fields](#waves) are below |
| `named[]` | every destroy, replacement and refusal by address, and every import and forget apart from them |
| `holes[]` | a resource instance the report could not read a change for, with its root, address and the reason; always present, and empty when nothing is missing |
| `roots[].plan` | paths to the root's full plan text and JSON, and the job that ran it |
| `roots[].binary` | the binary a root or Terragrunt unit ran: `name` (`tofu`, `terraform` or [`choudoufu`](/terragucci/concepts/glossary/#choudoufu)), `version`, and `pin`, where the root pinned that version (`.opentofu-version`, `.terraform-version`, `required_version` or `terragucci.yml version <glob>`); `pin` is absent for a root that runs the job's binary unpinned; for a unit, `terragrunt` with the Terragrunt `version` that ran it and `pin: terragrunt_version_constraint` when the unit pinned it (minor 24) |
| `deferred[]` | Terragrunt units planned once the units they wait for apply, and what each waits for |
| `mock_reads[]` | Terragrunt dependencies that would have read `mock_outputs`, with the upstream and the reason |
| `roots[].terragrunt` | for a Terragrunt unit: its `stack` (the directory of the explicit stack that generates it, else its parent directory), `stack_file`, the `terragrunt.stack.hcl` that generates it (minor 29), why it was selected, whether its plan is a provisional preview, and its result in Terragrunt's run report |
| `intent` | the description check's decision: status, whether it flagged the pull request, the decision, probability and threshold, model, `state_digest` and the destroys and replacements the text leaves out (`unmentioned`); present only after `respond description` ran on the report |
| `cost` | with `cost` set, on a `tf-plan` run or a `tf-apply` wave: the estimator, the currency, the monthly change and the totals before and after over the roots estimated, and per root (`roots[]`) the same three figures, the path of the estimator's output (`output`) or why there is no estimate (`error`) |
| `policy` | the policy check, when `policy` is on: engine, input mode, namespace, whether the policy came from the checkout or the base branch, the roots it denied and the warning count; with `policy.override` at base, `overriders` and the denied roots an override stands for, `overridden` |
| `roots[].policy` | the policy's verdict on the root's plan: `passed`, `denied` or `error`, the denial messages, the ids of the rules that denied (`rules`), the warnings and, for `error`, why it could not run; a denied root is `failed` and keeps its `changes` |
| `roots[].policy.override` | the [override](/terragucci/reference/policy/#overriding-a-denial) that stands for the root's plan and rules: `by`, `at`, `rules`, `reason`, `plan_digest`, the ledger line's `digest`, and `sealed`; on a `tf-apply` wave the root then applies and is `planned` |
| `redaction` | the marker that replaced sensitive values, and how many it replaced |
| `tips[]` | advice, each with the rule that produced it; absent with `tips: false` |
| `timings` | the run's roots or Terragrunt units, slowest first, and its slowest resource instances across roots |
| `roots[].resources` | on a `tf-apply` wave, for a root that applied or had nothing to apply: every managed resource it holds afterwards, from the plan's planned values, each with `address`, `type` and `provider`; never a value |
| `roots[].applied_changes` | on a `tf-apply` wave, for a root that applied: what the apply did to each resource (`actions`: `create`, `update`, `replace`, `delete`, `import`, `move` or `forget`), the top-level `attributes` an update or a replacement changed, by name, and `previous_address` for a move; never a value |
| `roots[].applied_changes[].record_versions` | for a choudoufu root: the record's versions after the apply, from `choudoufu live-history`: `kept`, `store`, `versions` (`version_id`, `last_modified`, `current`, `deleted`), `error` when they could not be listed, and `read` (minor 32) |
| `roots[].state` | on a `tf-apply` wave, for a root that applied or had nothing to apply: the state its backend holds afterwards, read from the object's metadata and never its contents: `backend`, `location` (`s3://<bucket>/<key>`, `gs://<bucket>/<key>`, `az://<account>/<container>/<key>` or the local file), `version_id` (S3's version id, a GCS generation, an Azure version id or snapshot), `versioning` (`on`; `off` when the backend keeps no history, as `local`, `pg`, `kubernetes`, `consul` and a plain `http` backend do; `unknown` when it may keep versions terragucci does not read) and a `note` saying why there is no version |
| `roots[].dependencies` | a Terragrunt unit's `dependency` and `dependencies` blocks: the units whose outputs it reads, as plain paths in its `terragrunt.hcl`; for a plain root, the roots [`waves.after`](/terragucci/reference/config/#waves) puts before it; absent when it names none |
| `roots[].steps` | the [steps](/terragucci/guides/run-steps/) that ran for the root, in order: `name`, `when` (such as `before-plan`), `status` (`passed`; `failed`, which failed the root; `approval`, a failed `on_failure: approve` step that holds the wave), `exit` and `seconds`; the steps' output stays in the job log |
| `roots[].reads` | the roots whose state the root reads through `terraform_remote_state`, or a Terragrunt unit's upstreams whose planned outputs it read through its `dependency` blocks: `upstream`, the block's label (`data`), and `outputs`: `planned`, the upstream's plan in the same run, with `unknown` naming the outputs known only once it applies, or `applied`, its state as it stands, with `why` in a pull request's plan |
| `roots[].unknown_reads` | the root's `terraform_remote_state` blocks whose [address](/terragucci/guides/track-cross-state-edges/#state-addresses) is not plain strings in the code: `data`, the block's label, and `why`; no edge orders the root after the root that writes that state (minor 30) |
| `roots[].unaddressed` | when a root of the run reads state through `terraform_remote_state`: why the root's own state has no address, so a reader of it is not ordered after it (minor 30) |
| `blast` | on a `tf-plan` run in which a root's plan changes something: `roots`, the roots whose plan changes a resource or an output, and `downstream`, nearest first, each root that reads the state of a root in the radius through `terraform_remote_state` or that `waves.after` puts after one (in a Terragrunt repo, each unit whose `dependency` or `dependencies` block names a unit in the radius), with the roots it reads there (`reads`), `depth` (1 when it reads a changed root itself), its `wave`, and whether the run `planned` it |
| `blast.resources` | when a root is downstream, for plain roots: each resource a plan changes (`root`, `address`, `actions`) and `reaches`, nearest first, each resource that depends on it with its `root`, its configuration `address`, and in another root `through`, the output it reads and the root that makes it (minor 31) |
| `waves[].held_by_steps` | the roots whose `on_failure: approve` step failed, so the gate holds the wave when it changes anything, whatever `gate` says |
| `roots[].timings` | the root's wall time, its plan's and, on a `tf-apply` wave, its apply's (`apply_seconds`); the slowest resources, provider calls, provider start-up and lock waits from the binary's spans; summed spans of a large estate; `source: terragrunt` when the times come from Terragrunt's run report; and a `note` when the binary sent nothing per resource |

### waves

| Field | On | Holds |
|---|---|---|
| `number`, `roots`, `set_digest` | every wave | the wave's number, its roots and the set digest |
| `approval` | every wave | `waiting`, `approved` or `not-required` on a `tf-apply` wave; `not-requested` on a plan |
| `gate` | a gated wave | the ledger's branch and path |
| `waiting_since` | a waiting wave | when it began waiting for an approval of this digest |
| `refused` | a `tf-apply` wave that planned but applied nothing | the `reason` (`approval`, `review` or `override` when its plans changed after one, `policy` when the policy denied a root), the digest `approved` and `by` whom, and the `roots` that moved or were denied |
| `review` | a waiting `tf-apply` wave under `approval: pr-review` | the `pull_request` whose approving review of its head would approve the wave, and the `url` to review it on |
| `review_digest` | a plan's wave | the set digest over the roots whose plan changes something, which `approval: pr-review` binds a review to |
| `waits` | a plan's wave | whether the gate or `cost.approve_above` will hold it |
| `state` | every wave | `planned` on a plan; on a `tf-apply` wave `waiting`, `applying` (its share jobs apply), `applied`, `refused` or `failed` |
| `reads` | a wave whose roots read other roots' state | the waves those roots are in |
| `replans_after` | a plan's wave that read outputs known only once these waves apply | it plans again after they apply and waits for an approval of that plan; its `review_digest` is null |
| `preview` | a `tf-apply` wave of Terragrunt units the merged pull request previewed (minor 25) | the `pull_request`, and per previewed unit (`units[]`) its `differences` from the preview, absent when it plans as previewed |
| `cost` | a wave, with `cost` set | the wave's monthly change and totals over the roots it estimated, the roots it could not estimate (`unestimated`), and with `cost.approve_above` at base the amount (`approve_above`) and whether the change is `over` it |

Its JSON Schema is `@intentius/terragucci/report.schema.json` in the package. [The reports bucket](/terragucci/reference/reports-bucket/) lists where each object lives and the schema of each.

## Reading it

| To find | Read |
|---|---|
| every destroy, replacement and refusal | `named[]`, filtered on `action` |
| the roots a group folds | `groups[].units`, matched to `roots[].path` |
| the digest an approval binds | `waves[].set_digest` of a `tf-apply` wave, over the `roots[].plan_digest` of each root whose plan changes something and, with `cost.approve_above` at base, the amount, the currency and the wave's monthly change; a plan's waves carry the same digest as `review_digest` |
| the digest a pull request review binds | `waves[].review_digest` in the plan report, compared with the same digest the wave plans after the merge |
| why a root is shown open | `roots[].why` |
| the full plan of a root | `roots[].plan` |
| the slowest resources of a run | `timings.resources`, then `roots[].timings.resources` |
| how long a root waited for its state lock | `roots[].timings.lock_waits`, with the attempts it took |
| what the policy denied or warned about in a root | `roots[].policy` |
| who overrode a denial, and why | `roots[].policy.override` |
| the binary and version each root ran | `roots[].binary` |
| the trace of the run, to search your tracing backend | `run.trace_id` |

Approvals stay on your repo's [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) branch. The report names each record's branch and path and never copies it.

## The index and the estate page

Every `index.json` in the bucket is `terragucci.report-index/v1` (JSON Schema `dist/report-index.schema.json`), one row per run, newest first.

| Row field | What it holds |
|---|---|
| `project`, `commit`, `stage`, `wave`, `finished`, `path` | the run, and its directory relative to the index |
| `share` | the share of a `tf-apply` wave split across jobs; each share has its own row |
| `roots`, `groups`, `totals`, `refused` | the report's counts |
| `failed` | roots that failed to plan or apply |
| `changed` | roots with a change; on a `tf-drift` row, the roots that drifted |
| `wave_digests` | on a `tf-plan` row, each wave's set digest and review digest: the digests an apply of the same plans binds |
| `drifted_roots` | on a `tf-drift` row, up to 50 of the roots that drifted |
| `drift_since` | on a `tf-drift` row that found drift, when the project's open drift was first found |
| `drift_cleared` | on a `tf-drift` row that found none after one that found some: `since`, when that drift was first found, and its `roots`; a later check of the same commit replaces the row that found it, so this row keeps it |
| `approval`, `waiting_since` | a `tf-apply` wave's gate, and when a waiting wave began waiting |
| `applied` | when a `tf-apply` wave finished applying |
| `overridden` | roots the policy denied that a recorded override let through; absent when none |
| `destroys`, `destroys_total` | up to 50 destroys and replacements, and how many there are when the row lists fewer |
| `commit_url`, `pull_request`, `pull_request_url`, `job_url`, `trace_url` | links |

From those rows and each project's newest run view, [`terragucci estate`](/terragucci/reference/cli/#estate) builds `estate.json`, schema `terragucci.estate/v1` (`dist/estate.schema.json`):

| Field | What it holds |
|---|---|
| `generated` | when the page was built; every `age_seconds` is as of then |
| `totals` | projects, waiting waves, drifted projects and roots, failed roots, unreadable indexes, `overridden_roots` when an override let a root through, and `resources` when a project has an inventory |
| `projects[]` | each project's latest plan, latest drift check, the waves of its newest applied commit, its waiting waves with `age_seconds`, `status` (`ok`, `no-index` or `error`), `inventory`: its resource count, the count of each type (`types`) and each root's resources with the wave that recorded them (`roots`), `states`: each root's state location, `versioning` and the version ids its applies left, newest first, each with its commit, wave and `report`, `edges`: each root that reads another's state (`consumer`, `producer`, `via`), with the consumer's last plan (`consumer_planned`) and the producer's last apply that changed it (`producer_applied`), each a run's `stage`, `commit`, `finished`, `wave`, `pull_request`, `version_id` and `report`, and a `status`: `stale` when the producer applied after that plan, `current`, or `unknown`, `run_view`: the commit of the [run view](/terragucci/concepts/waves-and-approvals/#the-run-view) the graph read, when a wave last wrote it (`updated`) and its `page`, and `ephemeral`: each live [ephemeral environment](/terragucci/guides/ephemeral-environments/), with its `pull_request`, its `roots` and each one's state `location`, the `commit` it `applied` from, when it `expires`, `approved_by`, and `status` (`live`, or `destroy-failed` until the sweep destroys it) |
| `recent[]` | the 20 newest runs across every project |
| `audit` | the [audit trail](/terragucci/reference/audit-trail/) beside the page: `page`, `entries` and `generated`, when `terragucci audit` wrote one |
| `history` | the resource history beside the page: `page`, how many addresses it holds (`resources`) and `generated`, once an apply changed a resource; each listed resource with a history links its section as `history` |
| `graph` | the dependency graph, once a project has a run view: `nodes`, each root by `project`, `root` and `wave`, and `edges`, each `from` a root `to` a root that reads its state through `terraform_remote_state`, or a Terragrunt unit `to` a unit that depends on it; an edge between two projects matched a read of a state outside the reader's project to the root of the other whose backend holds it |
| `dora` | the [delivery metrics](/terragucci/reference/delivery-metrics/) beside the page: `file` (`dora.json`), `generated`, and the estate's applied waves in their window as `deployments` |

A project's `inventory.json` is `terragucci.inventory/v1` (`dist/inventory.schema.json`). A `tf-apply` wave's upload replaces the list of each root it applied, unless the file holds a newer one.

| Field | What it holds |
|---|---|
| `roots[]` | by root path: `root`, the `commit`, `wave` and `finished` time of the wave that recorded the list, the wave's directory as `path`, relative to the project's `index.json`, and `resources`, each with `address`, `type` and `provider` |

Its `changes.json`, `terragucci.changes/v1` (`dist/changes.schema.json`), has one row per resource each applied `tf-apply` wave changed, newest first, up to 20,000 rows. A rerun of the same wave replaces its rows.

| Row field | What it holds |
|---|---|
| `address`, `type`, `actions`, `attributes`, `previous_address` | what the wave did to the resource, as in `roots[].applied_changes` |
| `root`, `commit`, `wave`, `finished`, `path` | the root and the wave, and the wave's directory relative to the project's `index.json` |
| `plan_digest`, `set_digest` | the root's plan digest, and the wave's set digest, which its approval binds |
| `pull_request` | the pull or merge request the wave applied |

`terragucci estate` also builds `history.json` beside the page, `terragucci.history/v1` (`dist/history.schema.json`), from every project's `changes.json` and the audit trail.

| Field | What it holds |
|---|---|
| `generated` | when it was built |
| `audit` | whether `audit.jsonl` was read for the approvers |
| `resources[]` | each address by `project` and `root`, with its `type`, its `id` (the anchor on `history.html`) and `applies`, oldest first: the row's actions, attributes, commit, wave, time and digests, the `report` link, and `approver` from the wave's apply entry in the audit trail, with that entry's `approval` id; `approver` is `null` when no gate held the wave, and absent when the audit trail has no entry for it |

## State versions

A project's `states.json` holds the version ids its roots' applies left (never a state's contents); its `schema` is `terragucci.state-versions/v1`, checked by `dist/state-versions.schema.json`. When a wave uploads its report, every root it applied adds its version, unless the root already lists that version. A root keeps its newest 20.

| Field | What it holds |
|---|---|
| `roots[].root`, `backend`, `location` | the root, its backend type, and `s3://<bucket>/<key>` or the local file |
| `roots[].versioning`, `note` | `on`, `off` (the backend keeps no history) or `unknown` (it may keep versions terragucci does not read) as the newest apply found it, and why there is no version |
| `roots[].checked` | when that apply finished |
| `roots[].versions[]` | newest first: `version_id`, the `commit`, `wave` and `finished` time of the wave that recorded it, and its directory as `path` |

## Cross-state edges

A project's `edges.json` holds, for each root, the roots whose state it reads and the runs that planned and applied it, as root paths and run facts with no state contents or output values. Its `schema` is `terragucci.state-edges/v1`, checked by `dist/state-edges.schema.json`. An upload writes it when a root of the report reads another's state, or when a `tf-apply` wave changed a root.

| Field | What it holds |
|---|---|
| `roots[].root` | the root |
| `roots[].reads[]` | the roots whose state it reads, `root` and `via` (`terraform_remote_state` from the report's `roots[].reads`, `dependency` from `roots[].dependencies`), as the newest plan or apply of the default branch found them; a pull request's code and a drift check never set them |
| `roots[].reads_seen` | when that run finished |
| `roots[].planned` | the newest run that planned the root (a pull request's plan, a drift check or an apply wave's plan; never a Terragrunt preview): `stage`, `commit`, `finished`, `wave`, `pull_request` and its directory as `path` |
| `roots[].applied` | the newest `tf-apply` wave that changed one of its resources, the same fields and the state `version_id` it left |

---

# The reports bucket

Source: https://intentius.io/terragucci/reference/reports-bucket/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/reference/reports-bucket/.
Write a script that reads estate.json and index.json at the top of my reports prefix with a read-only identity, validates each against the JSON Schema the page names, and prints every waiting wave with its project, age and report.
Read only: write nothing to the bucket.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

`reports.bucket` names an S3 or GCS bucket or an Azure Blob container, and terragucci writes under one prefix in it (`reports.prefix`, empty by default). A release adds keys and never moves one, so a program can rely on the layout below.

## Keys

| Key | Written by | What it is |
|---|---|---|
| `<prefix>/index.json`, `index.html` | every upload | every project's runs, newest first |
| `<prefix>/<project>/index.json`, `index.html` | every upload | one project's runs, newest first |
| `<prefix>/<project>/inventory.json` | a `tf-apply` wave's upload | the resources each root holds, from its newest applied wave |
| `<prefix>/<project>/changes.json` | a `tf-apply` wave's upload | what each applied wave did to each resource, newest first |
| `<prefix>/<project>/migrations/<name>.json` | wave 1 of `tf-apply`, when it runs a [state migration](/terragucci/reference/migration-files/) | the migration's record: each root's state version and digest before and after, never a state's contents |
| `<prefix>/<project>/states.json` | a `tf-apply` wave's upload | the state version id each root's applies left, newest first; never a state's contents |
| `<prefix>/<project>/edges.json` | an upload whose roots read another root's state, or a `tf-apply` wave that changed a root | each root's reads, its newest plan and its newest apply that changed it; never a state's contents |
| `<prefix>/<project>/ephemeral.json` | the [ephemeral](/terragucci/guides/ephemeral-environments/) job and the sweep, each time a pull request's copy applies or is destroyed | the live copies: each pull request's roots and state keys, its commit, when it applied and when it expires (`terragucci.ephemeral/v1`, the rows of the estate's `projects[].ephemeral`) |
| `<prefix>/<project>/<yyyy>/<mm>/<commit>/<stage>[-wave-<n>]/` | every upload | one run's report directory, below |
| `<prefix>/<project>/runs/<commit>/run.json`, `run.html` | each `tf-apply` wave job | the [run view](/terragucci/concepts/waves-and-approvals/#the-run-view): every wave of the commit's apply, its roots and what they read, where it stands, its blast radius and its timeline; `terragucci estate` reads it for the dependency graph |
| `<prefix>/traces/<trace id>.html` | an upload whose run sent a trace | a page that forwards to the run's `report.html` |
| `<prefix>/estate.json`, `estate.html` | [`terragucci estate`](/terragucci/guides/see-every-project/) | every project's latest plan, drift check and apply waves |
| `<prefix>/history.json`, `history.html` | [`terragucci estate`](/terragucci/guides/see-every-project/#change-history) | every resource address with each apply that changed it |
| `<prefix>/dora.json` | [`terragucci estate`](/terragucci/reference/delivery-metrics/) | the four DORA metrics per project and for the estate, week by week |
| `<prefix>/audit.jsonl`, `audit.html`, `audit.json` | [`terragucci audit`](/terragucci/reference/audit-trail/) | the audit trail, its page and its summary |
| `<prefix>/views/` | nothing | kept for a viewer's own files |

| Part | Value |
|---|---|
| `<project>` | the repo's `<host>/<path>`, such as `github.com/acme/infra`, slashes included; a repo with no git remote is named after its directory |
| `<yyyy>/<mm>` | the month the run finished, in UTC |
| `<commit>` | the full SHA |
| `<stage>` | `tf-plan`, `tf-drift` or `tf-apply`; a `tf-apply` directory ends in `-wave-<n>` |

## A run's directory

| File | What it is |
|---|---|
| `report.json` | the report, `terragucci.report/v1`; see [Report JSON schema](/terragucci/reference/report-schema/) |
| `report.html` | the report as a page, with `report.json` inline |
| `note.md` | the pull request note |
| `summary.txt` | the grouped plan as text |
| `gitlab-terraform.json` | GitLab's `reports:terraform` counts |
| `roots/<root>/plan.txt`, `roots/<root>/plan.json` | each root's full plan, and its JSON with sensitive values redacted |
| `roots/<root>/cost.json` | the estimator's output, with `cost` set |
| `intent.json` | the description check's decision, after `respond description` |

Links inside a run's files are relative, so they resolve wherever the bucket is served. A row's `path` in an `index.json` is relative to that index.

## JSON Schemas

Each object a program reads names its schema in its `schema` field. The package's `dist/` directory ships the matching JSON Schema:

| Object | `schema` | JSON Schema |
|---|---|---|
| `report.json` | `terragucci.report/v1` | `dist/report.schema.json`, also exported as `@intentius/terragucci/report.schema.json` |
| `index.json` | `terragucci.report-index/v1` | `dist/report-index.schema.json` |
| `estate.json` | `terragucci.estate/v1` | `dist/estate.schema.json` |
| each line of `audit.jsonl` | `terragucci.audit/v1` | `dist/audit.schema.json` |
| `inventory.json` | `terragucci.inventory/v1` | `dist/inventory.schema.json` |
| `changes.json` | `terragucci.changes/v1` | `dist/changes.schema.json` |
| `history.json` | `terragucci.history/v1` | `dist/history.schema.json` |
| `states.json` | `terragucci.state-versions/v1` | `dist/state-versions.schema.json` |
| `edges.json` | `terragucci.state-edges/v1` | `dist/state-edges.schema.json` |
| `dora.json` | `terragucci.dora/v1` | `dist/dora.schema.json` |
| `run.json` | `terragucci.run/v1` | `dist/run.schema.json` |

Within `v1` a release only adds fields, and an existing field keeps its meaning. A reader checks `schema` and ignores fields it does not know. The schemas leave objects open, so a validator accepts a field a later release added.

```bash
npm pack @intentius/terragucci
tar -xzf intentius-terragucci-*.tgz package/dist/estate.schema.json
```

[Report JSON schema](/terragucci/reference/report-schema/#the-index-and-the-estate-page) lists the fields of `index.json`, `estate.json`, `inventory.json`, `changes.json`, `history.json`, `states.json` and `edges.json`, [Delivery metrics](/terragucci/reference/delivery-metrics/#dorajson) the fields of `dora.json`, and [The audit trail](/terragucci/reference/audit-trail/#entry-fields) the fields of an audit entry.

## The views prefix

terragucci never writes or reads under `<prefix>/views/`. A tool that renders your reports, such as a static page built in a scheduled job, writes its files under `<prefix>/views/<tool>/`. An upload whose project name would start with `views` is refused before anything is written; give the repo a git remote.

Whatever serves the bucket serves `views/` too. A presigned link opens one object, and the [front door](/terragucci/guides/keep-reports-in-a-bucket/#the-front-door) serves every key under the prefix to whoever your identity provider signs in.

## Reading it

| To read | An identity needs |
|---|---|
| every project's runs and the estate | `GetObject` on `<prefix>/*index.json` and `<prefix>/estate.json` |
| every project's resources | `GetObject` on `<prefix>/*inventory.json` |
| every root's state versions | `GetObject` on `<prefix>/*states.json` |
| every root's cross-state edges | `GetObject` on `<prefix>/*edges.json` |
| every live ephemeral environment | `GetObject` on `<prefix>/*ephemeral.json` |
| every resource's history | `GetObject` on `<prefix>/history.json`, or on `<prefix>/*changes.json` for the rows without approvers |
| a run's report | `GetObject` on `<prefix>/*/report.json` |
| the audit trail | `GetObject` on `<prefix>/audit.jsonl` |
| the delivery metrics | `GetObject` on `<prefix>/dora.json` |

A reader needs no list permission: an index row names each run's directory, and the report names each root's plan files.

---

# Environment variables and credentials

Source: https://intentius.io/terragucci/reference/environment/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/reference/environment/.
List every variable and secret this repo's pipeline needs and which job gets each. Print names only.
Do not write secret values anywhere. Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

The config names variables and never holds a value. Put secrets in your forge's secret store and expose them to the job that needs them.

**GitHub**
    A repository secret (Settings > Secrets and variables > Actions), read as `secrets.<NAME>`. The run's own token is `github.token`.
**GitLab**
    A masked CI/CD variable (Settings > CI/CD > Variables). `GITLAB_TOKEN`, a project access token with the `api` scope, is its forge token.
**Forgejo**
    As on GitHub, under Settings > Actions > Secrets.

## Forge tokens

| Variable | Used by | Needs |
|---|---|---|
| the run's own token (`github.token` on GitHub and Forgejo) | the generated jobs that post or push | comments and statuses; apply also writes [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle), and `fmt` pushes to the branch |
| `GITLAB_TOKEN` | the generated jobs on GitLab | a project access token with the `api` scope, as a masked variable; with `comments:` set it also needs the Developer role; with `gitlab.token: protected` it is also a protected variable, and only default-branch jobs get it |
| `GITHUB_TOKEN`, `GITLAB_TOKEN`, `FORGEJO_TOKEN` | `reconcile`, `rollout` and `respond --mode apply`, by the project's forge | push branches and open pull requests in the projects they touch |
| `TG_TOKEN` | the comment, status, note and respond steps | set by the job; set it yourself outside a pipeline |
| `GITEA_TOKEN` | nothing | dropped with the other runner tokens from every step that runs a pull request's code |

`token_env` renames the variable. Those commands never merge, so the token needs no merge rights.

| Never reaches the binary or Terragrunt | Where |
|---|---|
| `TG_TOKEN`, `TG_MERGE_TOKEN`, `GITHUB_TOKEN`, `GH_TOKEN`, `GITLAB_TOKEN`, `CI_JOB_TOKEN`, `FORGEJO_TOKEN`, `GITEA_TOKEN`, `ACTIONS_RUNTIME_TOKEN` | the plan, apply, drift and respond stages, and `validate`, `live-check` and the policy engine in the check job |
| any variable holding the value of `TG_TOKEN` or `TG_MERGE_TOKEN` | the same |
| `TF_` variables | pass as set, so a provider's token goes in a `TF_VAR_` variable | [What this covers](/terragucci/reference/pipeline/#pull-request-code-access).

### Jobs that run a pull request's code

On GitHub and Forgejo these jobs hold no forge token while the change's code runs.

| Guard | Covers |
|---|---|
| checkouts keep no credentials in the git config | every job below |
| the steps that run the change's code start without `TG_TOKEN`, `GITHUB_TOKEN`, `GH_TOKEN`, `GITEA_TOKEN`, `FORGEJO_TOKEN` or `ACTIONS_RUNTIME_TOKEN` | every job below |
| those steps start their shell again without the token | Forgejo, whose runner gives every step its token whatever `permissions:` says |

| Job | The token is used by |
|---|---|
| `check` | no step; after a failed check on a branch, the `fmt` job pushes the formatting |
| `plan` | the step before the checkout, which posts `terragucci/plan` pending; the `plan-note` job then posts the note and the status from the plan report |
| `replan` | the step that reads the comment, before the head is checked out; the `replan-note` job posts |

The GitLab check job drops `TG_TOKEN`, `TG_MERGE_TOKEN`, `GITLAB_TOKEN` (or the `token_env` variable) and `CI_JOB_TOKEN` before it runs anything; the `fmt` job pushes the formatting. `GITLAB_TOKEN` stays with the plan job unless `gitlab.token: protected` makes it a protected variable. [Where the scrub ends](/terragucci/reference/threat-model/#token-scrub-limits).

### GitLab-managed state

The binary never gets `CI_JOB_TOKEN`, so the `http` backend takes its credentials from `TF_` variables in `env:` ([pipeline reference](/terragucci/reference/pipeline/#gitlab-managed-state)).

## Reports

Set these on the plan job when `reports.bucket` is set, and in the environment `terragucci mcp` starts in. `AWS_` variables are read for an `s3://` bucket only.

| Variable | Meaning |
|---|---|
| `AWS_WEB_IDENTITY_TOKEN_FILE` | the job's OIDC token, which a job with `oidc` writes; with `reports.role` the job assumes that role with it |
| `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | bucket credentials without `reports.role`, from same-named secrets |
| `AWS_SESSION_TOKEN` | for temporary credentials, when set; mapped from the secret of the same name like the two keys |
| `AWS_ROLE_ARN` | the role assumed with no `reports.role` and no keys |
| `AWS_ROLE_SESSION_NAME` | the session name of an assumed role; `terragucci-report` when not set |
| `AWS_ENDPOINT_URL_S3`, `AWS_ENDPOINT_URL` | a store that is not AWS; `reports.endpoint` takes precedence |
| `AWS_ENDPOINT_URL_STS`, `AWS_ENDPOINT_URL` | the STS that answers `AssumeRoleWithWebIdentity`; `https://sts.<region>.amazonaws.com` when neither is set |
| `AWS_REGION`, `AWS_DEFAULT_REGION` | the bucket's region, in that order; `us-east-1` by default |
| `GOOGLE_APPLICATION_CREDENTIALS` | a `gs://` bucket: the credentials file, which a job with `oidc.gcp` writes |
| `AZURE_STORAGE_KEY` | an `az://` container: the account key, from the same-named secret; it wins over the job's OIDC identity |
| `ARM_TENANT_ID`, `ARM_CLIENT_ID`, `ARM_OIDC_TOKEN_FILE_PATH` | an `az://` container without a key: the identity and token a job with `oidc.azure` gets |
| `AZURE_AUTHORITY_HOST` | Entra ID's address for that token; `https://login.microsoftonline.com` when not set |

## State

What reads a root's state where it is (the version an apply records, `state export`, `unlock-state`, a migration) uses the credentials the backend would: those its configuration names, else these.

| Variable | Meaning |
|---|---|
| `GOOGLE_OAUTH_ACCESS_TOKEN` | `gcs`: a bearer token, as the backend's `access_token` |
| `GOOGLE_BACKEND_CREDENTIALS`, `GOOGLE_CREDENTIALS` | `gcs`: a credentials file, or its JSON, as the backend's `credentials` |
| `GOOGLE_APPLICATION_CREDENTIALS` | `gcs`: the credentials file when none of the above is set, which a job with `oidc.gcp` writes |
| `GOOGLE_BACKEND_IMPERSONATE_SERVICE_ACCOUNT`, `GOOGLE_IMPERSONATE_SERVICE_ACCOUNT` | `gcs`: the service account to act as, as the backend's `impersonate_service_account` |
| `GOOGLE_BACKEND_STORAGE_CUSTOM_ENDPOINT`, `GOOGLE_STORAGE_CUSTOM_ENDPOINT` | `gcs`: the JSON API's address, as the backend's `storage_custom_endpoint` |
| `ARM_ACCESS_KEY`, `ARM_SAS_TOKEN` | `azurerm`: the account key or a SAS, as the backend's `access_key` and `sas_token` |
| `ARM_TENANT_ID`, `ARM_CLIENT_ID`, `ARM_OIDC_TOKEN_FILE_PATH` | `azurerm` without a key or SAS: the identity a job with `oidc.azure` gets, which reads blobs through Entra ID |
| `ARM_ENVIRONMENT`, `ARM_METADATA_HOSTNAME`, `ARM_METADATA_HOST` | `azurerm`: the cloud (`public`, `china`, `usgovernment`), or the host of its metadata, which names the storage suffix |
| `ARM_SNAPSHOT` | `azurerm`: `true` as the backend's `snapshot = true` |
| `AZURE_CLIENT_ID` | set to a root's client with `azure.roles`, when the job sets it |

## Secrets the config names

| Config key | Default name | Holds |
|---|---|---|
| `agent.comment.key_secret` | `ANTHROPIC_API_KEY` | the model's API key, given to the agent's step alone |
| `agent.token_env` | none, required | the token the agent's change is pushed with |
| `apply.merge_token_env` | none, required on Forgejo with `apply.merge: auto`, and on GitLab with `apply.when: pull-request` | a token that may push to the default branch |
| `cost.key_secret` | `INFRACOST_API_KEY` | the cost estimator's API key; the plan jobs get it as `INFRACOST_API_KEY` |
| `decide.token_env` | none, required for `jev` | the typed-decision service's bearer token |
| `notify.slack` | none | a Slack incoming webhook address; the apply jobs get it as `TERRAGUCCI_SLACK_WEBHOOK` |
| `notify.teams` | none | a Microsoft Teams incoming webhook address; the apply jobs get it as `TERRAGUCCI_TEAMS_WEBHOOK` |
| `notify.webhook` | none | a webhook's address for the JSON event; the apply jobs get it as `TERRAGUCCI_WEBHOOK` |
| `notify.webhook_key` | none, required with `notify.webhook` | the key that signs the event; the apply jobs get it as `TERRAGUCCI_WEBHOOK_KEY` |

The drift job also gets `notify.slack` and `notify.teams`. The apply jobs get `notify.relay`, a name rather than a secret, as `TERRAGUCCI_RELAY`.

## Secrets and variables you pass

```yaml
pass:
  secrets: [TF_VAR_db_password]
  vars: [TF_VAR_region]
```

| Forge | The job's environment |
|---|---|
| GitHub, Forgejo | `TF_VAR_db_password: ${{ secrets.TF_VAR_db_password }}` and `TF_VAR_region: ${{ vars.TF_VAR_region }}` in plan, re-plan, every apply job, `apply-comment`, `confirm`, `resume`, drift, and the ephemeral job and its sweep |
| GitLab | unchanged: every job reads the project's CI/CD variables by name already |

The pipeline holds the names alone. The check job, the note jobs, `fmt`, `tips`, `publish` and the agent jobs get none. The plan job runs a pull request's code, so a passed secret reaches that code, as the providers' credentials do; a fork's pull request gets no plan job. Forgejo keeps a secret's or variable's name in capitals and reads it in any case, so the job gets `TF_VAR_db_password` spelled as the root's variable is.

## The relay

[`terragucci relay`](/terragucci/guides/approve-from-chat/) reads these from its own environment, in your cloud. No generated job gets them.

| Variable | Default | Meaning |
|---|---|---|
| `TERRAGUCCI_RELAY_REPO` | none, required | the repo's https clone address, with no credential in it |
| `TERRAGUCCI_RELAY_TOKEN` | none, required | the approve-only token; the relay refuses to start with a token that administers the repo, may push to its default branch, or on GitLab has the `api` scope |
| `TERRAGUCCI_RELAY_FORGE` | read from the host | `github`, `gitlab` or `forgejo`, for a host other than github.com and gitlab.com |
| `TERRAGUCCI_RELAY_PRINCIPAL` | `terragucci-relay` | the name each approval records as `relayedBy` |
| `SLACK_SIGNING_SECRET` | none | the Slack app's signing secret; without it the relay refuses every Slack request |
| `TEAMS_WEBHOOK_SECRET` | none | the key Teams showed when you made the outgoing webhook; without it the relay refuses every Teams request |
| `TERRAGUCCI_RELAY_SLACK_RESPONSE` | `https://hooks.slack.com/,https://hooks.slack-gov.com/` | the address prefixes a Slack `response_url` may have; the relay posts its answer to no other |
| `PORT` | `8080` | the port it serves on |
| `telemetry.headers_secret` | none | the value of `OTEL_EXPORTER_OTLP_HEADERS` |
| `token_env` | by forge, see above | the forge token |

## Module publishing

Only the `publish` job gets these, as secrets or, on GitLab, protected masked variables.

| Variable | Meaning |
|---|---|
| `TERRAGUCCI_REGISTRY_USER` | the registry user |
| `TERRAGUCCI_REGISTRY_PASSWORD` | its password or token |
| `TERRAGUCCI_REGISTRY_INSECURE` | `1` for a registry without TLS |
| `COSIGN_PRIVATE_KEY` | with `modules.attest`, the private key of the cosign key pair, as `cosign generate-key-pair` writes it |
| `COSIGN_PASSWORD` | with `modules.attest`, that key's password |

Git tags and the release ledger are pushed to `origin` with the job's checkout, so they need no variable.

## Cloud roles over OIDC

With `oidc`, jobs trade the forge's token for cloud roles.

```yaml
oidc:
  plan_role: arn:aws:iam::111122223333:role/terragucci-plan
  apply_role: arn:aws:iam::111122223333:role/terragucci-apply
  audience: sts.amazonaws.com
```

| Key | Meaning |
|---|---|
| `plan_role` | the read-only role the plan job assumes |
| `apply_role` | the write role, for apply jobs only, including [apply before merge](/terragucci/reference/pipeline/#apply-before-merge) |
| `audience` | the AWS token's audience; `sts.amazonaws.com` when omitted |
| `roles` | AWS roles by root glob, `{ plan, apply }` each: a root plans and applies with the pair of the first glob it matches, and a root no glob matches with `plan_role` and `apply_role`, which are then optional. Plain roots only; a Terragrunt repo sets [`terragrunt.credentials`](/terragucci/reference/pipeline/#credentials) |
| `gcp.workload_identity_provider` | `projects/<number>/locations/global/workloadIdentityPools/<pool>/providers/<provider>` |
| `gcp.plan_service_account`, `gcp.apply_service_account` | the service accounts the plan and apply jobs impersonate |
| `gcp.token_url` | the STS endpoint; `https://sts.googleapis.com/v1/token` when omitted |
| `gcp.roles` | service accounts by root glob, `{ plan, apply }` each; a root no glob matches takes `gcp.plan_service_account` and `gcp.apply_service_account`. Plain roots only |
| `azure.audience` | `api://AzureADTokenExchange` when omitted; `...USGov` or `...China` for those clouds |
| `azure.tenant_id`, `azure.subscription_id` | the Entra ID tenant and the subscription the jobs work in |
| `azure.plan_client_id`, `azure.apply_client_id` | the identities plan and apply sign in as |
| `azure.roles` | client IDs by root glob, `{ plan, apply }` each; a root no glob matches takes `azure.plan_client_id` and `azure.apply_client_id`. Plain roots only |

Plan runs the pull request's code, so it gets the read-only role. The config rejects one role for both. Forks get no plan job, so nothing reaches their pull requests.

Under `roles`, the jobs carry each stage's roles in `TERRAGUCCI_ROOT_ROLES`. The stage sets each root's `AWS_ROLE_ARN` from it; the binary and steps assume that role with the job's token, as does the state version read. A role per environment keeps each environment's roots out of another's state ([Keep each environment's roles to its own state](/terragucci/guides/scope-state-access/)); `config check` warns when a role reaches another environment's state.

`gcp.roles` and `azure.roles` work the same way, through `TERRAGUCCI_ROOT_GCP_SERVICE_ACCOUNTS` and `TERRAGUCCI_ROOT_AZURE_CLIENTS`. A root's binary gets a copy of the job's credentials file that impersonates its service account, as `GOOGLE_APPLICATION_CREDENTIALS`, and its client as `ARM_CLIENT_ID`. Each client needs a federated credential for the same subjects as the job's.

Your role's trust policy must accept the forge's issuer and your repo. Forgejo needs version 15 and Runner 12.5 or later. [Credentials](/terragucci/reference/pipeline/#credentials) covers GCP and Azure.

| Forge | Issuer |
|---|---|
| GitHub | `https://token.actions.githubusercontent.com` |
| GitLab | your GitLab URL |
| Forgejo | your Forgejo URL followed by `/api/actions` |

The plan role is used on the pull request and on the default branch: re-plan, drift and `confirm` run the default branch's workflow. Trust both subjects for plan, and only the default branch's for apply.

| Forge | Plan role trusts | Apply role trusts |
|---|---|---|
| GitHub | `repo:<owner>/<repo>:pull_request` and `repo:<owner>/<repo>:ref:refs/heads/<default branch>` | `repo:<owner>/<repo>:ref:refs/heads/<default branch>` |
| GitLab | `project_path:<group>/<project>:ref_type:branch:ref:*` | `project_path:<group>/<project>:ref_type:branch:ref:<default branch>` |
| Forgejo | `repo:<owner>-<owner id>/<repo>-<repo id>:pull_request` and `repo:<owner>-<owner id>/<repo>-<repo id>:ref:refs/heads/<default branch>` | `repo:<owner>-<owner id>/<repo>-<repo id>:ref:refs/heads/<default branch>` |

On GitLab a merge request's plan job carries its source branch in the subject, so the plan role trusts every branch of the project. Anyone who can push a branch can assume it; keep it read-only. Azure matches a federated credential's subject exactly, so on GitLab the plan identity needs a credential that matches on a claims expression instead.

A repo with Actions on before Forgejo 16 keeps `repo:<owner>/<repo>` until Actions is toggled. `GET /api/v1/repos/<owner>/<repo>` shows both IDs.

Older Forgejo or runner versions need `oidc` unset and static credentials on the runner.

In a Terragrunt repo, roles can follow unit paths ([The generated pipeline](/terragucci/reference/pipeline/#terragrunt)).

## Agent integrations

`agent.token_env` holds the agent's forge token; the agent's jobs hold no cloud role. See [Responses](/terragucci/reference/responses/#runtime).

| Variable | Set for |
|---|---|
| `TG_AGENT_PROMPT`, `TG_AGENT_MAX_TURNS` | the agent's step of `agent.comment` and `agent.drift`: the prompt's path and the turn limit |
| `TG_ISSUE` | `drift-agent-push`: the drift issue the drift job opened, which the pull request names and is linked on |

## Traces and metrics

The [observability reference](/terragucci/reference/observability/#turning-it-on) explains how to turn them on.

| Variable | Meaning |
|---|---|
| `OTEL_EXPORTER_OTLP_ENDPOINT` | the collector's OTLP/HTTP base URL |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | one signal's full URL |
| `OTEL_EXPORTER_OTLP_HEADERS` | headers sent with every request; `telemetry.headers_secret` maps a secret into it |
| `OTEL_EXPORTER_OTLP_TRACES_HEADERS`, `OTEL_EXPORTER_OTLP_METRICS_HEADERS` | headers for one signal, added to the shared ones |
| `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` | `grpc` is refused, since terragucci sends OTLP over HTTP |
| `OTEL_TRACES_EXPORTER`, `OTEL_METRICS_EXPORTER` | `none` turns one signal off |
| `OTEL_SDK_DISABLED` | `true` turns both off |
| `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES` | the service name, `terragucci` by default, and extra resource attributes |
| `TRACEPARENT` | the parent span of the stage's trace |

## Other variables you can set

| Variable | Flag | Meaning |
|---|---|---|
| `TERRAGUCCI_SCHEDULE` | | GitLab, on a pipeline schedule: `comments` makes the schedule's pipelines run the `comments` job alone; a schedule without it runs drift |
| `TERRAGUCCI_TERRAGRUNT` | | the `terragrunt` executable to run; `terragrunt` on the path by default |
| `TERRAGUCCI_TERRAMATE` | | the `terramate` executable `init` and `terragucci terramate generate` run; `terramate` on the path by default |
| `TERRAGUCCI_ATMOS` | | the `atmos` executable `init`, `terragucci atmos write` and, with `oidc.roles`, `terragucci config check` run; `atmos` on the path by default |
| `TOFU_INSTALL_DIR` |  | where `terragucci install` and the stages put the binary, one directory per tool and version, so a runner that keeps it reuses each version; `$RUNNER_TEMP/terragucci-bin` or the temp directory by default |
| `RUNNER_TEMP` |  | set by GitHub and Forgejo runners |
| `TF_CLI_ARGS`, `TF_CLI_ARGS_plan`, `TF_CLI_ARGS_apply` |  | a `-lock-timeout` here replaces the default `-lock-timeout=5m` |
| `TF_DATA_DIR`, `TF_WORKSPACE` |  | where a root's initialised backend is recorded and which workspace it runs in; a `tf-apply` wave reads both to find the state whose version it records |
| `TG_LOCK_STALE` |  | with [choudoufu](/terragucci/concepts/glossary/#choudoufu), seconds after which a wave takes over the resources another run holds, whatever its forge says of that run; 7200 by default |
| `TG_BACKEND_BOOTSTRAP` |  | Terragrunt repos, `tf-apply`: when the job sets it, the wave passes it to Terragrunt as it is, so `false` keeps the wave from creating or changing a bucket that `generate.disable_init: false` would bootstrap |
| `TG_LOCK_POLL` |  | with choudoufu, seconds between a waiting wave's checks of the resources another run holds; 10 by default |
| `TG_PROGRESS_SECONDS` |  | with choudoufu, seconds between an applying wave's reads of its estates' records for [its progress](/terragucci/concepts/waves-and-approvals/#progress); 5 by default |
| `TG_BASE` | `--base` | the ref policy is read from, such as `origin/main`; the target branch by default |
| `TG_BRANCH` |  | the default branch; other pushes read policy from `origin/<that branch>` |
| `TG_PR`, `TG_SHA`, `TG_HEAD` |  | the pull request number, commit and head branch |
| `TG_PLAN_JSON` |  | set for the `cost.command` estimator: the path of the root's stored plan, `show -json` with sensitive values redacted; `TG_ROOT` names the root |
| `TG_STAGE`, `TG_STEP`, `TG_ROOT`, `TG_REPO`, `TG_PLAN_FILE` |  | set for a [step](/terragucci/guides/run-steps/): the stage (`tf-plan`, `tf-apply` or `tf-drift`), the moment (such as `before-plan`), the root, the checkout's path and, after a plan and before an apply, the plan file |
| `GITHUB_ACTOR`, `GITLAB_USER_LOGIN`, `USER` |  | the approver for `terragucci approve` without `--actor`; under `approval: sealed` it must be in `.chant/allowed_signers` |
| `env:` in the config |  | variables every job gets; values only, never secrets |

## Forge variables

A local run needs none of these.

| Forge | Variables |
|---|---|
| GitHub and Forgejo | `GITHUB_REPOSITORY`, `GITHUB_SERVER_URL`, `GITHUB_API_URL`, `GITHUB_RUN_ID`, `GITHUB_WORKFLOW_REF`, `GITHUB_SHA`, `GITHUB_REF_NAME`, `GITHUB_BASE_REF`, `GITHUB_HEAD_REF`, `GITHUB_EVENT_NAME`, `GITHUB_EVENT_PATH`, `GITHUB_STEP_SUMMARY`, `GITHUB_OUTPUT`, `GITHUB_PATH`; Forgejo adds `FORGEJO_ACTIONS`, `GITEA_ACTIONS` |
| GitHub and Forgejo, for OIDC | `ACTIONS_ID_TOKEN_REQUEST_URL`, `ACTIONS_ID_TOKEN_REQUEST_TOKEN`, `ACTIONS_RUNTIME_TOKEN` |
| GitLab | `GITLAB_CI`, `CI_PROJECT_PATH`, `CI_PROJECT_ID`, `CI_PROJECT_DIR`, `CI_PROJECT_URL`, `CI_SERVER_URL`, `CI_SERVER_HOST`, `CI_SERVER_FQDN`, `CI_SERVER_PROTOCOL`, `CI_API_V4_URL`, `CI_PIPELINE_ID`, `CI_PIPELINE_URL`, `CI_PIPELINE_SOURCE`, `CI_JOB_URL`, `CI_COMMIT_SHA`, `CI_COMMIT_BEFORE_SHA`, `CI_COMMIT_BRANCH`, `CI_DEFAULT_BRANCH`, `CI_MERGE_REQUEST_IID`, `CI_MERGE_REQUEST_TITLE`, `CI_MERGE_REQUEST_DESCRIPTION`, `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME`, `CI_MERGE_REQUEST_SOURCE_BRANCH_SHA`, `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH`, `CI_MERGE_REQUEST_TARGET_BRANCH_NAME` |

## Generated job variables

Internal; a value set in `env:` is overwritten.

| Variable | Set for |
|---|---|
| `TG_MERGE_TOKEN` | `pr-merge` only, from `apply.merge_token_env`, else `TG_TOKEN`; on GitLab also the `comments` job, which starts the `mr-apply` pipeline with it; no job running pull request code has it |
| `TERRAGUCCI_MR`, `TERRAGUCCI_NOTE`, `TERRAGUCCI_HEAD` | GitLab, `apply.when: pull-request`: the variables the `comments` job starts the `mr-apply` pipeline with, naming the merge request, its note and its head; `mr-apply` reads all three again from GitLab |
| `TERRAGUCCI_AGENT_MR`, `TERRAGUCCI_AGENT_NOTE`, `TERRAGUCCI_AGENT_HEAD` | GitLab, `agent.comment`: the variables the `comments` job starts the agent's pipeline with, naming the merge request, the `/terragucci agent` note and the head; `agent` and `agent-push` each read the merge request and the note again from GitLab |
| `TERRAGUCCI_REVIEW_MR`, `TERRAGUCCI_REVIEW_HEAD` | GitLab, `review.agent`: the variables the `comments` job starts the review's pipeline with, naming the merge request and the head to review |
| `TG_WAVES` | the `pr-merge` job: the waves the `apply-comment` job applied, for its reply |
| `TG_FORGE`, `TG_TOKEN`, `TG_PR`, `TG_SHA`, `TG_HEAD`, `TG_BEFORE`, `TG_BRANCH`, `TG_BASE`, `TG_ROOT`, `TG_WAVE`, `TG_OPEN`, `TG_OUTCOME`, `TG_OUTCOME_JSON` (apply jobs with `notify`) | steps naming a pull request, wave or root |
| `TG_PLAN_RESULT` | the `plan-note` and `replan-note` jobs: the plan job's result |
| `TERRAGUCCI_EPHEMERAL_SUFFIX` | Terragrunt repos, the `ephemeral` job, while it prepares a unit: `-pr-<n>`, which a unit's `remote_state` key reads; empty in every other job |
| `TG_ACTION` | the `ephemeral` job on GitHub and Forgejo: the pull request event's action; `closed` destroys the pull request's [ephemeral environment](/terragucci/guides/ephemeral-environments/) |
| `TG_ATLANTIS_COMMENTS` | every job, `1`, with `atlantis_comments: true`: the comment commands read `atlantis plan` and `atlantis apply` |
| `TG_NO_FORGE_TOKEN` | a step that runs a pull request's code, once its shell has started again without the forge token variables |
| `TF_IN_AUTOMATION`, `TF_INPUT` | every job: `1` and `0` |
| `TG_NON_INTERACTIVE`, `TG_PARALLELISM`, `TG_TF_PATH`, `TG_DOWNLOAD_DIR`, `TG_PROVIDER_CACHE`, `TG_PROVIDER_CACHE_DIR`, `TG_AUTH_PROVIDER_CMD`, `TERRAGUCCI_REPO`, `TERRAGUCCI_PHASE`, `TERRAGUCCI_TG_ROLES`, `TG_IAM_ASSUME_ROLE_WEB_IDENTITY_TOKEN` | Terragrunt repos; `TG_IAM_ASSUME_ROLE` is never set |
| `TG_BACKEND_BOOTSTRAP` | Terragrunt repos, a `tf-apply` wave, when `generate` gives a unit `disable_init: false` and the job does not set it: `true`, so Terragrunt creates or updates the state bucket ([Bucket bootstrap](/terragucci/guides/generate-root-files/#bucket-bootstrap)) |
| `TERRAGUCCI_TG_NEXT`, `TERRAGUCCI_TG_PHASE` | Terragrunt repos, the plan stage: the binary the `TG_TF_PATH` wrapper runs, and whether Terragrunt is planning or checking for mock reads, so a later layer is planned on its upstream's planned outputs |
| `TERRAGUCCI_OIDC`, `TERRAGUCCI_GCP_TOKEN_FILE`, `TERRAGUCCI_OIDC_GCP`, `TERRAGUCCI_OIDC_AZURE`, `AWS_WEB_IDENTITY_TOKEN_FILE`, `AWS_ROLE_ARN`, `AWS_ROLE_SESSION_NAME`, `GOOGLE_APPLICATION_CREDENTIALS`, `ARM_USE_OIDC`, `ARM_OIDC_TOKEN_FILE_PATH`, `ARM_TENANT_ID`, `ARM_SUBSCRIPTION_ID`, `ARM_CLIENT_ID` | jobs with `oidc` |
| `TERRAGUCCI_ROOT_ROLES` | jobs with `oidc.roles`: the stage's roles by root glob, as JSON `[[glob, role], ...]`; each root's `AWS_ROLE_ARN` comes from it |
| `TG_AGENT_PROMPT`, `TG_AGENT_MAX_TURNS` | the agent comment's job: the prompt file and the turn limit |
| `TG_REVIEW_PROMPT` | the review command's step: the prompt file, which is also its stdin |
| `TG_DEFAULT_BRANCH` | the review job: the default branch, read from the event, that the instructions come from |
| `TF_HTTP_ADDRESS`, `TF_PLUGIN_CACHE_DIR` | read from your job: GitLab state lowers parallelism; the roots of a stage share the cache, or one of the stage's own when it is unset |
| `TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE` | set to `true` for a root whose `.terraform.lock.hcl` does not pin its providers at the binary's registry, so its init takes them from the shared cache instead of downloading over a copy another plan is running ([Applies side by side](/terragucci/reference/pipeline/#applies-side-by-side)) |
| `TF_HTTP_USERNAME`, `TF_HTTP_PASSWORD`, `TF_HTTP_LOCK_ADDRESS`, `TF_HTTP_UNLOCK_ADDRESS`, `TF_HTTP_LOCK_METHOD`, `TF_HTTP_UNLOCK_METHOD` | read from your job or shell, as the binary reads them, on [GitLab-managed state](/terragucci/reference/pipeline/#gitlab-managed-state): the serial each apply records, `state export`, `unlock-state` and ephemeral copies |

---

# The plan report

Source: https://intentius.io/terragucci/reference/report/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/reference/report/.
Run `npx terragucci stage tf-plan` in this repo, open terragucci-report/report.html and tell me which roots destroy or replace something, and which sensitive values were redacted.
Read only. Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

Each `tf-plan`, `tf-apply` wave and `tf-drift` run writes one JSON report, the source of everything a person reads.

## Running it

The plan job writes the report for every pull request and merge request. Its note is the one plan note, and the `terragucci/plan` status takes its counts from it.

**GitHub**
    Kept as the `terragucci-report` artifact, and the note names the run.

**GitLab**
    The job's artifacts hold the HTML report, and the note links it. The merge-request widget reads `gitlab-terraform.json`.

**Forgejo**
    The same as GitHub.

With [a served bucket](#report-storage) the copy there is linked instead.

Run it locally from the repo:

```bash
npx terragucci stage tf-plan
```

| Case | Roots planned |
|---|---|
| no base | every root |
| a pull request, `--base <ref>` or `TG_BASE` | the roots the change reaches: its directory, local modules, var files, or state read from a changed root; none, and the note says so |
| with [`synth`](/terragucci/guides/plan-cdk-terrain-stacks/#planned-stacks) | the command runs on the base too: roots whose synthesized files or local modules differ, new and removed ones, and the roots that read their state; the note counts the unchanged ones |
| with `synth`, when the base cannot be synthesized | every root, and the note says why |

It writes to `terragucci-report/`.

| File | What it is |
|---|---|
| `report.json` | the report |
| `report.html` | the HTML report |
| `note.md` | the plan note |
| `summary.txt` | the grouped summary, as the job log shows it |
| `gitlab-terraform.json` | the counts for GitLab's merge-request widget |
| `roots/<root>/plan.txt` | the root's full plan, as the binary printed it, with every value the plan marks sensitive masked |
| `roots/<root>/plan.json` | the same plan as `show -json`, with sensitive values redacted |
| `roots/<root>/cost.json` | with `cost` set, the estimator's output for the root |
| `issue.md` | `tf-drift` only: the drift issue's body ([Drift](/terragucci/reference/stages/#drift)) |
| `issue.json` | `tf-drift` only: what the run did to the issue (`opened`, `updated`, `closed`, `left-open` or `none`) with its number and address |

The stage still writes the report when a root refuses to plan, and exits 1. [CLI commands](/terragucci/reference/cli/#plan-and-stage) lists the flags.

## Reviewer view

| View | Where | What it shows |
|---|---|---|
| Plan note | the pull request or merge request | each group's diff, every destroy by name, the wave plan, the approval command, each root's whole plan collapsed, links to the full report and each plan, and a last line with the terragucci taco, an image the docs site serves |
| HTML report | wherever the report is kept | every group, root and wave, with filters, and where the run spent its time |
| Merge-request widget | GitLab | create, update and delete counts, from a `reports:terraform` artifact |
| Text summary | the job log | the grouped summary |

## The plan note

The note comments the plan back to the pull request, grouped. A group of two roots shows one diff:

```diff
  # terraform_data.cfg will be updated in-place
~   resource "terraform_data" "cfg" {
        id     = "9167c516-893b-56eb-9652-6061b49febdd"
~       input  = {
~           greeting = "hi" -> "hello"
            # (2 unchanged attributes hidden)
        }
    }
```

| Part | What it holds |
|---|---|
| Group | the diff of its first root (or instance) as the binary printed it: each attribute that changes with its value before and after, nested blocks, `(known after apply)`; once per group, then the roots that make the same change |
| Values that differ | the attributes whose values differ between the group's roots, by name |
| Each root's plan | the root's whole plan in a collapsed block, with its `Plan:` line as the title and a link to its `plan.txt` |
| Diff colors | each line's `+`, `-`, `~` or `-/+` moved to the first column, so the forge colors additions and removals |

A Terragrunt unit's plan is kept as JSON only, so its group shows the attribute names.

### Comment limits

| Forge | Limit the note keeps to |
|---|---|
| GitHub | 65,536 characters, what the API accepts |
| GitLab | 1,000,000 characters, GitLab's documented limit |
| Forgejo | 1,000,000 characters; Forgejo sets none |

The pipeline's first line and the line an apply adds to a stale note come off the limit. A note over it stays one comment and cuts, in this order, until it fits:

| Order | Cut | Kept |
|---|---|---|
| 1 | roots' whole plans and groups' diffs, whichever is largest first | each cut root named and linked to its `plan.txt`; each cut group by attribute name |
| 2 | whole groups, from the last | destroys, replacements and refusals, dropped only after every group |

A `Cut:` line names what went and links the full report.

### Note links

| The run | The note links |
|---|---|
| `reports.url` set | the bucket's `report.html`, and each root's `plan.txt` beside it |
| `reports.bucket` without `reports.url` | `report.html` and each `plan.txt` in the bucket, presigned, with the time the links stop working |
| GitLab, no bucket | the job's artifact `report.html`, and each `plan.txt` beside it |
| GitHub or Forgejo, no bucket | the run, whose `terragucci-report` artifact holds the report |
| a runner that keeps no forge artifact, no bucket | the run, and no report |

Presigned links live 7 days at most. An S3 link signed with a role's session stops when the session ends.

## Open and folded sections

| Item | Shown as |
|---|---|
| destroy, replacement, refusal | open, with the attributes that forced each replacement |
| root whose change differs from every group | open |
| type where one wrong value reaches far | open, marked with why |
| `prevent_destroy` | open |
| attributes that differ between roots of a group | open |
| group of identical changes | folded, one diff with a count |
| update that only touches tags or descriptions | folded |
| value known only after apply | folded |
| root with no changes | folded |

Highlighted types, and the reason the report gives:

| Types | Why |
|---|---|
| IAM: `aws_iam_*`, `google_*_iam_*`, `azurerm_role_assignment`, Kubernetes roles and bindings | changes who may do what |
| `aws_security_group`, its rules, `google_compute_firewall`, `azurerm_network_security_*` | changes what traffic gets in or out |
| `aws_network_acl` and its rules | changes what traffic a subnet allows |
| `aws_kms_*`, `google_kms_*`, `azurerm_key_vault_key` | data encrypted under the key depends on it |
| `aws_route53_*`, `google_dns_*`, `azurerm_dns_*`, Cloudflare records | changes where names resolve |

A change to one of these that only touches tags stays folded.

## Back to the full plan

Each root's full plan is kept beside the report as printed and as JSON. The HTML report links every group, root and named change to its plan and job.

The plan link opens the root's plan as the binary printed it:

The header names the commit and the job, and the pull request when there is one. With `telemetry.trace_url` set, the trace id opens the trace; see [Traces and metrics](/terragucci/reference/observability/#trace-links). The HTML report is one file that makes no network calls.

## Script access

`report.json` sits beside every `report.html`, which also carries it inline:

```bash
sed -n '/id="terragucci-report"/,/<\/script>/p' report.html | sed '1d;$d' | jq '.named[] | select(.action == "delete") | .address'
```

[Report JSON schema](/terragucci/reference/report-schema/) lists every field.

Approvals stay on your repo's [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) branch. The report links to each record and never copies it. [The audit trail](/terragucci/reference/audit-trail/) reads the two together.

## Sensitive values

`show -json` prints sensitive values in plain text. terragucci redacts each one before a plan is kept, and the report page counts them.

| Value | In the report |
|---|---|
| sensitive value, default of a sensitive variable | `(sensitive, redacted by terragucci)`, in `plan.json` and the report alike, wherever the value appears, including an attribute the plan does not mark, such as the `output` of a `terraform_data` whose `input` is sensitive |
| the same value in `plan.txt` and the note | `(sensitive value)`, as the binary prints it, wherever the value appears, including an attribute the plan does not mark |
| policy denial or warning | redacted before it reaches the report, note or log; the [policy](/terragucci/reference/policy/) itself reads the unredacted plan |
| write-only attribute | its version (`*_wo_version`), labelled as such; the value is never in the plan |
| ephemeral value | not reported |
| import, forget | named apart from destroys; a forget leaves the resource running |

Digests are taken before redaction, so an approval binds the plan as planned.

## Report storage

By default a report is a CI artifact of the plan job, kept as long as your forge keeps artifacts. To keep them longer, name a bucket in `terragucci.yml` and rerun `npx terragucci init`.

| `reports.bucket` | Store | API |
|---|---|---|
| `s3://<bucket>` | S3, or any S3-compatible store | S3, Signature Version 4 |
| `gs://<bucket>` | Google Cloud Storage | the JSON API |
| `az://<account>/<container>` | Azure Blob Storage | the Blob REST API |

On S3 the job takes the first identity that applies:

| Order | Identity | Used when |
|---|---|---|
| 1 | `reports.role`, assumed with the job's OIDC token (`AWS_WEB_IDENTITY_TOKEN_FILE`) | `reports.role` is set |
| 2 | `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, plus `AWS_SESSION_TOKEN` | the keys are set |
| 3 | `AWS_ROLE_ARN`, assumed with `AWS_WEB_IDENTITY_TOKEN_FILE` | no role and no keys |

| Setting | Config key | Variables read, in order | Default |
|---|---|---|---|
| store endpoint | `endpoint` | `AWS_ENDPOINT_URL_S3`, `AWS_ENDPOINT_URL` | AWS |
| region the requests are signed for | none | `AWS_REGION`, `AWS_DEFAULT_REGION` | `us-east-1` |

`reports.endpoint` wins over the variables.

| Store | Identity, first that applies | Link |
|---|---|---|
| GCS | `GOOGLE_APPLICATION_CREDENTIALS`: an `external_account` file (what `oidc.gcp` writes) or a `service_account` key | V4 signed URL, signed through IAM `signBlob` or with the key |
| Azure Blob | `AZURE_STORAGE_KEY`; then `ARM_TENANT_ID`, `ARM_CLIENT_ID` and the token in `ARM_OIDC_TOKEN_FILE_PATH` (what `oidc.azure` sets), traded at `AZURE_AUTHORITY_HOST` | service SAS with the key; user delegation SAS with OIDC |

`reports.role` is for S3 only. [Keep reports in a bucket](/terragucci/guides/keep-reports-in-a-bucket/#3-give-the-job-an-identity-that-writes-only-reports) says why reports get their own identity.

```yaml
reports:
  bucket: s3://acme-terragucci
  prefix: reports
  url: https://reports.acme.example
  role: arn:aws:iam::123456789012:role/terragucci-reports
```

`url` is the bucket's browser address; terragucci never derives it from the bucket name. With it the note links the bucket's `report.html` and `report.json` records it as `run.report_url`. Without it the note links the bucket's copy presigned; see [Where the note links](#note-links).

A run's report and plans land under one path holding the full commit SHA, so links are relative and work in the bucket:

| Forge | SHA |
|---|---|
| GitHub, Forgejo | `GITHUB_SHA` (for a GitHub pull request, the test merge commit) |
| GitLab | `CI_COMMIT_SHA` |

```
reports/github.com/acme/infra/2026/10/4f1a9c0d2e7b8a6c5d4e3f2a1b0c9d8e7f6a5b4c/tf-plan/report.html
reports/github.com/acme/infra/2026/10/4f1a9c0d2e7b8a6c5d4e3f2a1b0c9d8e7f6a5b4c/tf-apply-wave-2/report.json
```

## Tips

With `tips` on, the default, the report ends with advice on how your roots are set up, such as a floating version. Each tip names its rule, and none fails a run or changes a gate. `tips: false` removes them. See [Tips](/terragucci/reference/tips/).

## The report index

Each upload rewrites the two index files, `index.html` and `index.json`.

| Item | Value |
|---|---|
| Where | one index for the project, and one at the top of the prefix for all projects |
| A row per run | its counts, its failed and changed roots, a wave's gate and how long it has waited, and up to 50 destroys |
| Rows kept | 500, plus the newest row of every project, stage and wave beyond them |
| Built on it | [`terragucci estate`](/terragucci/reference/cli/#estate), one page for every project, and [`terragucci audit`](/terragucci/reference/audit-trail/), which reads each `tf-apply` row's report |
| Retention | your bucket's lifecycle rule |

:::caution
A static site serving the index publishes every report in the bucket, so put the site behind your identity provider and keep the bucket private. [Keep reports in a bucket](/terragucci/guides/keep-reports-in-a-bucket/#5-serve-the-index) has the choices.
:::

---

# Runtimes

Source: https://intentius.io/terragucci/reference/runtimes/

Each stage is a job on your forge's CI, and its schedule a workflow trigger. `runtime` in [your config file](/terragucci/reference/config/) takes one value, `forge`, the default.

| Forge | What runs the jobs | Credentials |
|---|---|---|
| GitHub | GitHub Actions | per-job OIDC roles or secrets |
| GitLab | GitLab CI, with the summary as the merge-request note | per-job OIDC roles or CI variables |
| Forgejo | Forgejo Actions, on your own instance | per-job OIDC roles or secrets |

## Approvals outside CI

[`terragucci approve`](/terragucci/reference/cli/#approve), run on your laptop, records the approval on the [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) branch and restarts the waiting wave with your forge token. With `apply.resume` set, the scheduled resume job picks up any wave it could not restart ([Resume after an approval](/terragucci/reference/pipeline/#resume-after-an-approval)).

Each stage also runs from your shell, with your own credentials, as `terragucci stage <name>`; [Stages](/terragucci/reference/stages/) lists them.

---

# Validation

Source: https://intentius.io/terragucci/reference/validation/

Each smoke claim runs twice and passes only when both runs hold: as written it must pass, and with its property broken on purpose (the BREAK) it must fail.

<details>
<summary>What is left</summary>

</details>

Every check behind the grids is listed in [the per-forge claims](#the-per-forge-claims) and [the example's checks](#the-examples-checks) below.

| Forge | What runs |
|---|---|
| Forgejo | a Forgejo server and its runner |
| GitHub | the generated workflow, run by `act` against a mock GitHub API |
| github.com | the published release's generated workflow on GitHub-hosted runners, in a public plan-only repo |
| GitLab | GitLab CE and its runner |

## The per-forge claims

`reconcile` follows a [control repo](/terragucci/concepts/control-repo/)'s pull request until it is merged and applied. Pinned CI images run the `tg-` claims on a two-unit Terragrunt repo and the `cdf-` claims on a [choudoufu](/terragucci/concepts/glossary/#choudoufu) estate.

The github.com claims run the newest published release against real GitHub pull request events and statuses, comments and reviews, and OIDC tokens. Every resource there is a `terraform_data`, so nothing needs a cloud account. The limits:

| Limit | What runs instead |
|---|---|
| no cloud role | `oidc` checks each job's token against GitHub's published keys, its repo, run, audience and role, and trades it with nothing; the trade with STS is proven on Forgejo |
| no bucket | `report-keys`, `report-oidc` and `estate-job` write to [floci](/terragucci/concepts/glossary/#floci), the AWS emulator, run in the job beside a stand-in for STS that checks each token and role as `oidc` does |
| one GitHub account | the refusals of a commenter with no write access and of a pull request from a fork are proven on Forgejo; the apply-before-merge pull requests are opened by a workflow, so the account that runs the claims may approve them |
| no model key | the agent comment and the refused-wave job run a stand-in agent that makes one edit or prints the summary input |
| BREAK for the locking and report claims alone | `pr-lock`, `pr-lock-fmt`, `apply-serial`, `pr-apply-lock`, `pr-apply-stale`, `report-keys`, `report-oidc` and `estate-job` run a second time with their property broken (a lock dropped from [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle), a guard cut from the committed pipeline, `undiverged` left out of `apply.requires`, or the job's keys or token taken away); the other claims have no BREAK run, so they read "passes" |

<details>
<summary>Every per-forge claim</summary>

</details>

## The example's checks

These checks run against the [tutorial's example](/terragucci/tutorial/) on a local Forgejo with OpenTofu. The GitLab column lists the ones that also run on a local GitLab CE and its runner. There, each gets a small repo holding the pipeline `terragucci init` writes for GitLab.

The Terraform and choudoufu columns list the core checks run again on that binary in its CI image. They use `binary:` in each repo's `terragucci.yml`, on a copy of the repo written for the binary under names of its own:

| Binary | What the copy changes |
|---|---|
| Terraform | each root's `required_version`, which pins OpenTofu's release line, takes that release or later, and its `.terraform.lock.hcl` is the one Terraform writes, for Terraform's registry |
| choudoufu | each root's backend becomes a `live` block: an estate per root, its records in an S3 record store; a service reads the platform's logs bucket through `terraform_estate_outputs` instead of `terraform_remote_state`, and its registration in that bucket is a `terraform_data`, since choudoufu admits no `aws_s3_object`; `drift` is left out, since it is a config error there, which the drift row shows |

<details>
<summary>Every check on the example</summary>

</details>

The same setup runs on your laptop. [The tutorial](/terragucci/tutorial/) boots it with one command and walks through each feature.

## Running it yourself

See [CONTRIBUTING.md](https://github.com/INTENTIUS/terragucci/blob/main/CONTRIBUTING.md).

---

# Waves and approvals

Source: https://intentius.io/terragucci/concepts/waves-and-approvals/

A shared module change goes out in batches, each after the last; a batch waits only when the [gate policy](#waiting-waves) holds it.

## Waves

The roots in `waves.canary` go first, then one dependency layer per wave, so no root in a wave reads another in it. The report's wave 3 is the gate `wave-3`.

A root's dependencies are the roots whose state it reads through `terraform_remote_state`. For plain roots that read nothing of each other, [`waves.after`](/terragucci/reference/config/#root-order) gives the order instead:

```yaml
waves:
  after:
    app: [database]
    database: [network]
```

```text
wave 1  network
wave 2  database   (after network)
wave 3  app        (after database)
```

A pull request that changes `network` plans all three, and its blast radius names `database` and `app`.

Terragrunt units split the same way, the canary units' layers first. Each wave is one `terragrunt run --all` behind its own gate. Once approved, it applies exactly the plans its job saved.

| Where | Terragrunt waves come from |
|---|---|
| `init` | `terragrunt find`; without Terragrunt on the path, the plain paths in each unit's `dependency` and `dependencies` blocks |
| each apply job | `terragrunt find` in the job, which splits a wave whose units read each other; the last job also runs any wave past the jobs `init` wrote |

## Approval binding

The wave's set digest is what an approval binds, so it covers exactly those plans. Under `approval: ledger`, the default, that is all it takes, so anyone who can push to `chant/lifecycle` can approve in anyone's name. `approval: sealed` also requires its ssh seal to verify against the signers file.

The `approval` key, the signers and the gates in [`chant.workspace.json`](/terragucci/concepts/glossary/#chantworkspacejson) come from the applied commit's first parent (the default branch before an applying pull request), so a change cannot loosen its own rule. Only a multi-commit rebase breaks this; [merge or squash such changes](/terragucci/guides/approve-a-wave/#rule-commit).

A gated wave reads the newest approval of its gate:

| That approval names | The wave |
|---|---|
| the digest it plans now | applies, after it records on `chant/lifecycle` that it used the approval |
| another digest, which a run applied | waits for an approval of its own digest, with the command to give it |
| another digest, which no run applied | applies nothing and exits 4: its plans changed after approval |

An approval never counts for a digest other than its own. Under `on-destructive` a re-plan with no destroy applies; under `never` nothing is refused.

## Plans are made late

Each wave plans on real outputs after the last one applied, and an approval binds only that plan's digest. A Terragrunt unit never plans on `mock_outputs` ([details](/terragucci/guides/use-terragrunt/#differences)).

## Linked roots

A root that reads another root's state through `terraform_remote_state` goes in a later wave. When a pull request's change reaches both, the reading root plans on the other root's planned outputs instead of its last applied ones:

| An output it reads | In the pull request's plan |
|---|---|
| known when the upstream plans | the new value |
| known only once the upstream applies | `(known after apply)` |
| of an upstream the change does not reach | the applied value |

The plan note lists each root planned this way and the outputs it read before they were known. A wave that read such an output plans again once the waves it reads have applied, then waits for an approval of that plan. No digest for it appears in the note, and under `approval: pr-review` the pull request's review does not approve it. With only known outputs read, the wave plans the same digest again when its upstream applies as planned, so an approval or review of the note's digest still counts.

For that plan terragucci adds `terragucci_linked.tf` with a local holding the upstream's planned outputs and points the root's references to the block at it. The files are restored after the plan. A root in Terraform's JSON syntax, such as a CDK Terrain stack's `cdk.tf.json`, is linked the same way: its backend and its `terraform_remote_state` blocks order the waves, and its references are rewritten inside their `${...}` templates. These still plan on the applied state, and the report's `roots[].reads` says why:

| Case | It plans on |
|---|---|
| an upstream that has never applied | nothing yet: the root waits for it, and the report and note name it as waiting |
| a block with `count` or `for_each` | the applied state |
| a plan on the planned outputs that fails, such as a `for_each` over a value known only after apply | the applied state |
| a block in a child module | the applied state; it does not order the waves either |
| `terragucci plan` on your machine | the applied state |

A Terragrunt unit's `dependency` is previewed through Terragrunt itself, and a unit that reads a value known only once its upstream applies is not planned at all: see [Use Terragrunt](/terragucci/guides/use-terragrunt/#later-layers).

## The run view

With [`reports.bucket`](/terragucci/guides/keep-reports-in-a-bucket/) set, each apply also writes one page for its commit, `<prefix>/<project>/runs/<commit>/run.html`, and its data, `run.json`. It shows the waves left to right with their roots and the roots each reads, and where each wave stands:

| State | The wave |
|---|---|
| not started | no job of it has run on this commit yet |
| waiting | waits for an approval; the page gives its digest and the approval command |
| applying | is applying, or its [share jobs](#a-wide-wave-across-jobs) are |
| applied | applied, or had nothing to apply |
| refused | applied nothing: its plans changed after an approval, or the policy denied a root |
| failed | a root failed to plan or apply |

Each wave's job rewrites its own column when it starts applying and when it ends, and links its report. A wave's `report.json` says the same in `waves[].state`, and a pull request's report marks the waves that plan again in `waves[].replans_after`.

Below the waves the page has two more parts:

| Part | Shows |
|---|---|
| Blast radius | the roots whose plan in a wave changes something, every root that reads their state through `terraform_remote_state` or that `waves.after` puts after them (in a Terragrunt repo, every unit whose `dependency` or `dependencies` block names it), followed through, and the dependency graph of the commit's roots with both marked |
| Timeline | each wave's plan, its wait at the gate and its apply on one time axis, a wait that has not ended drawn open, and the time in each as a table |

A wave that waited shows the plan that asked for the approval and the later plan that applies. In `run.json` each wave carries `changed` (the roots whose plan changes something) and `spans`, each with `phase` (`plan`, `gate` or `apply`), `start` and, once it ended, `end`. Each root carries `state`, the state its backend block names, and `external`, its reads of a state no root of the repo holds, which the [estate page](/terragucci/guides/see-every-project/) matches to other projects' roots.

### Progress

With [choudoufu](/terragucci/concepts/glossary/#choudoufu), a wave's column also follows each resource its plans change while it applies:

The wave reads its estate's records every 5 seconds (`TG_PROGRESS_SECONDS`), not the apply's output. A resource is done once its record is written or removed, which choudoufu does as each resource's apply returns. It is in flight once the resources it depends on are done, and waiting before that. A resource with no record of its own is done when its root's apply returns. While a wave applies, the page reloads every 15 seconds, the job writes the same list to `terragucci-report/progress.json`, `run.json` carries it in `waves[].progress`, and the [estate page](/terragucci/guides/see-every-project/) shows the counts.

### Blast radius in the plan note

Pull requests get the same radius in their plan note, by wave: the roots whose plan changes something and each downstream root that reads their state. A root the run did not plan, such as one `--root` left out, is marked "not planned in this run".

```text
**Blast radius:** 1 root changes (`envs/dev/platform`), and 3 roots downstream read their state:

- `envs/dev/orders` (wave 2) reads `envs/dev/platform`
- `envs/dev/payments` (wave 2) reads `envs/dev/platform`
- `envs/dev/search` (wave 2) reads `envs/dev/platform`
```

In a Terragrunt repo the radius is the units whose own plan changes something, not a preview, and each unit that depends on them through a `dependency` or `dependencies` block, followed through:

```text
**Blast radius:** 1 unit changes (`live/dev/vpc`), and 1 unit downstream depends on them:

- `live/dev/app` (wave 2) depends on `live/dev/vpc`; not planned in this run
```

The note leaves it out when nothing reads or depends on a changed root. `report.json` carries it as `blast`.

### Resources in the radius

For plain roots, the note also lists each changed resource and the resources that depend on it, in its own root and in each root that reads an output it reaches:

```text
**By resource:**

- `aws_sqs_queue.jobs` in `queue` (update) reaches:
  - `aws_sqs_queue_policy.jobs`
  - `aws_lambda_event_source_mapping.jobs` in `worker`, through output `jobs_arn` of `queue`
  - `aws_lambda_function.worker` in `worker`, through output `jobs_arn` of `queue`
```

The edges come from each plan's references: expressions, `count`, `for_each`, `depends_on`, module arguments and outputs, and locals. Between roots, a resource is listed only when it reads an output the change reaches, through `terraform_remote_state` or `terraform_estate_outputs`. A reader of `worker`'s outputs is followed the same way. A root the run did not plan stays in the root list only. `report.json` carries the list as `blast.resources`.

## Waiting waves

The gate policy decides which waves wait for a person.

| Policy | Waits for an approval when |
|---|---|
| `always` | the wave has at least one change; a wave whose plans change nothing never waits |
| `on-destructive` | the wave's plans destroy or replace something |
| `never` | never; only pull request review and default branch protection stand in front of it |

A waiting wave exits with code 3 and prints the approval command; run it, then rerun the stage. A rerun resumes after the approval or failed root and never applies a root twice.

## A wide wave across jobs

`parallelism` bounds what one job runs at once, and every wave gets a single job, so a wave of a few hundred roots keeps one runner busy while the rest idle. Set `waves.jobs` to spread it over several:

```yaml
waves:
  jobs: 3
```

| Job | What it does |
|---|---|
| `apply-wave-<n>` | plans every root, runs the policy, decides the gate on the set digest and records the approval it uses, then hands each plan digest to the shares and changes nothing |
| `apply-wave-<n>-share-<s>` | plans its part again and applies it if each digest matches what `apply-wave-<n>` decided; otherwise exits 4 and changes nothing |

Shares run side by side as far as runners are free, and the next wave starts after the last of them. Each wave still has one gate with one ledger record and one approve command. Each share copies its report to the bucket under `tf-apply-wave-<n>-share-<s>`.

In a Terragrunt repo the wave's job plans every unit with one `run --all`, and each share plans and applies its own units with one `run --all --filter`. When the last wave splits, an `apply-rest` job after its shares runs any wave Terragrunt's edges cut past the pipeline's, as the last wave's job does otherwise.

On GitLab the shares take each other's place in the apply resource group, which runs one job at a time, so with `waves.jobs` the apply jobs hold a lock on the remote instead, as on Forgejo; the pipeline's `CI_JOB_TOKEN` cannot push, so the project's token does. `init` refuses the key under `apply.when: pull-request`. A comment's apply and the resume job keep a single job per wave.

## Applies side by side

Two pushes that change different roots apply at the same time, and a root's own applies take turns at its state lock; with [choudoufu](/terragucci/concepts/glossary/#choudoufu), waves wait only for a run changing one of their resources. A wave a newer push superseded stands down. With `apply.when: pull-request`, an applying pull request also locks each root it reaches until it merges or closes. With `locks: plan`, a pull request holds that lock from its first plan. [Per forge](/terragucci/reference/pipeline/#applies-side-by-side).

## Next

- [Approvals as records in your repo](/terragucci/concepts/approvals-as-records/)
- [Approve a waiting wave](/terragucci/guides/approve-a-wave/)
- [Fix a refused wave](/terragucci/guides/fix-a-refused-wave/)

---

# Plan grouping

Source: https://intentius.io/terragucci/concepts/why-plans-are-grouped/

A shared module change can reach two hundred roots with near-identical plans, and a reviewer scrolling for the odd one out can miss a destroy.

## Grouping

terragucci normalizes each root's changes and groups the roots whose changes are the same.

```text
180 roots: identical change (update aws_iam_role.app, tags)
 15 roots: the same, plus replace aws_lambda_function.worker
  5 roots: read these individually
destroys: prod-eu/db (delete aws_db_instance.main)
```

The reviewer reads the shared change once, then the 20 roots that differ.

## Rules by change

| Change | In the report |
|---|---|
| destroys, replacements, refusals, imports, forgets | named, never grouped; a forget is not counted as a destroy |
| roots that differ from every group | open |
| IAM and security group changes | open |
| KMS and DNS changes | open |
| groups of identical changes | folded |
| updates to tags or descriptions only | folded |
| values known after apply | folded |
| roots with no changes | folded |

Each root and group links to its full plan in text and JSON. Approvals bind the plan digests, taken before redaction or rendering, so the summary's wording never changes what was approved.

## Next

- [The plan report](/terragucci/reference/report/) shows the note, the HTML report and the JSON.
- [Waves and approvals](/terragucci/concepts/waves-and-approvals/)

---

# Approvals as records in your repo

Source: https://intentius.io/terragucci/concepts/approvals-as-records/

An approval is a record on your repository's `chant/lifecycle` branch. [`terragucci approve`](/terragucci/reference/cli/#approve) writes it, naming the plan it approves.

| Question | Answer |
|---|---|
| What does a record hold? | the wave's stage and set digest; no plans and no report. The report links the record, so the branch alone says who approved what |
| Why a branch? | each approval is a commit `git log` can show, kept with the code across CI tools; every runtime reads the one branch, so a laptop approval counts wherever the apply runs |
| Why does it name the plan? | a changed plan needs a new approval, and a refusal is the safe outcome; [Fix a refused wave](/terragucci/guides/fix-a-refused-wave/) recovers from one |
| Who can write one? | any writer, or a GitHub job with `contents: write`, can push a line naming someone |
| Who approves? | people; terragucci writes no code that approves for an agent, agent recipes only comment and open pull requests, and no agent holds or is listed with a signing key |

## Valid approvals

A pushed line counts and binds the plans under the default `approval: ledger`. Any writer can name any person.

| `approval` | A wave's approval counts when | Read from |
|---|---|---|
| `ledger` | a line names the wave's digest | `terragucci.yml` at base |
| `pr-review` | a line names the digest, or the merged pull request's head was approved by a writer other than its author (on GitLab, after its latest push) and the wave plans what the review saw | `terragucci.yml` at base |
| `sealed` | a line names the digest and its seal, made by `terragucci approve --sign`, verifies against `.chant/allowed_signers` (or the file `.chant/trust.json` names) | `terragucci.yml`, [`chant.workspace.json`](/terragucci/concepts/glossary/#chantworkspacejson) and the signers file at base |

These files come from the applied commit's first parent, so a change cannot judge itself. Only a multi-commit rebase merge breaks that rule; merge or squash those. [`agent-push`](/terragucci/reference/pipeline/#paths-an-agent-cannot-change) refuses edits to these files. Block force pushes and deletion on `chant/lifecycle` ([per forge](/terragucci/guides/approve-a-wave/#push-access-to-chantlifecycle)).

## Next

- [Waves and approvals](/terragucci/concepts/waves-and-approvals/)
- [Approve a waiting wave](/terragucci/guides/approve-a-wave/)
- [The audit trail](/terragucci/reference/audit-trail/): one record of every project's approvals and applies, with its overrides and refused waves

---

# Glossary

Source: https://intentius.io/terragucci/concepts/glossary/

A page links a word here on first use, unless the page explains it.

## Your code

### root

A directory whose files configure a provider or hold a state block (`backend`, `cloud` or choudoufu's `live`). `init` finds them, or `roots:` names them by glob. Every stage runs the binary once in each.

A root with a `cloud` block on remote execution runs on HCP Terraform's workers, where the job's `oidc` roles do not reach. Local execution keeps the runs in your CI.

### forge

The service that hosts your repository and runs its pipelines: GitHub, GitLab or Forgejo. The workflow terragucci writes for yours runs on its runners.

### control repo

A repo whose `terragucci.yml` lists your projects under `projects` and their shared settings under `defaults`. `reconcile` opens a pull request in each project that changes, and each project's own pipeline applies. [Control repo](/terragucci/concepts/control-repo/).

### unit

A Terragrunt directory with a `terragrunt.hcl`. `terragrunt find` lists units and each is treated as a root. A directory of units is an implicit stack, shown as a report label.

### layer

A step of the dependency order that one root's reads of another set (`terraform_remote_state`, choudoufu's `terraform_estate_outputs` or a Terragrunt `dependency` block). `init --dry-run` counts them; `tf-plan` plans one at a time.

### wave

A batch `tf-apply` applies behind one approval, gated as `wave-1`, `wave-2`. Wave 1 holds the canary and each later wave one layer; for Terragrunt units a wave is one `terragrunt run --all`.

### canary

The roots named in `waves.canary`, applied first in wave 1 so a bad change reaches a few roots before the rest.

### plan digest

A hash of one root's plan. The job takes it before anything is redacted or rendered.

### set digest

The hash over the plan digests of the roots in a wave whose plan changes something. An approval names it, and the wave refuses to apply if any of its plans changes or a root starts or stops changing. A pull request's plan note shows it for each wave.

### gate

Where a wave waits for a person, per the `gate` setting: `on-destructive` (default), `always` or `never`. A waiting job exits 3 and prints its `terragucci approve` command.

## Approvals

### chant

The record format terragucci writes to [`chant/lifecycle`](#chantlifecycle): approvals, applies and lock releases, one line each. [chant](https://intentius.io/chant/) is the toolkit terragucci is built on. Approvers' keys are in [`.chant/allowed_signers`](#chantallowed_signers).

### chant/lifecycle

A branch holding the apply job's records and one commit per approval. Let only the apply job's identity push to it and block force pushes and deletion. [Approvals as records](/terragucci/concepts/approvals-as-records/) says why, and chant's [gate steps](https://intentius.io/chant/guide/ops/#gate-steps) describe the gate ledger it holds.

### chant.workspace.json

The file at the repository root, written by `init` under `approval: sealed`, listing the wave gates under `identity.gates`. It has nothing to do with Terraform workspaces.

### identity.gates

The gates in `chant.workspace.json` (`init` lists all under `approval: sealed`) whose approvals count only with a seal that verifies against `.chant/allowed_signers` as of the parent commit. With no `approval` key, any gate listed here keeps the repo sealed.

### .chant/allowed_signers

The signers file holds one ssh public key per approver in ssh-keygen's allowed_signers format and is read from the commit before the one applied. [Set up the signers file](/terragucci/guides/approve-a-wave/#set-up-the-signers-file). chant documents the file under [`chant workspace signers`](https://intentius.io/chant/cli/workspace-signers/).

### pr-review

The `approval:` mode where the merged pull request's approving review of its head approves a gated wave, when the wave plans what the review saw. Any `terragucci approve` of the digest still counts, as under `ledger`. [Approve by review](/terragucci/guides/approve-a-wave/#approve-by-review-approval-pr-review).

### seal

The ssh signature `terragucci approve --sign` puts on an approval. Under `approval: sealed` an unverified or edited record counts for nothing. `ledger` (the default) and `pr-review` need no seal.

## Other tools

### fountain

A separate runtime that runs pipeline stages on a long-lived machine. terragucci's pipelines run on your forge's CI and never on [fountain](https://github.com/managoat/fountain).

### steward

fountain's word for the machine that runs stages for one environment. terragucci has no steward.

### floci

A local stand-in for the AWS API that the tutorial applies to, so it needs no AWS account. It keeps no tags, so every root's tags show as drift.

### choudoufu

The OpenTofu fork from the team behind terragucci ([Choose your binary](/terragucci/guides/use-a-binary/#choudoufu), [its repository](https://github.com/INTENTIUS/choudoufu)). `binary: choudoufu` keeps the same six stages, and the four that run a binary (`tf-check`, `tf-plan`, `tf-apply`, `tf-drift`) run choudoufu.

| Feature | What it does |
|---|---|
| State | one record per resource in an S3 backend; the state file is a cache, never the record of what you own |
| Writes | each record write is conditional, so two writes to one record settle at the API, with no lock table or database ([locking with choudoufu](/terragucci/concepts/locking-and-staleness/#with-choudoufu)) |
| Tags | each resource carries its identity as a tag the next plan reads back |
| Stages | `tf-check` also runs its live check, and wave reports show state lock waits |

## Words that mean something else in Terraform

| Here | What it means here | Not to be confused with |
|---|---|---|
| `chant.workspace.json` | the file that lists the sealed gates | a Terraform or HCP Terraform workspace; each root plans in `default` unless `TF_WORKSPACE` says otherwise |
| `--mode apply` on `rollout`, `respond` and `reconcile` | push the commit or open the pull request that the dry run described | `terraform apply`, which none of the three runs |
| layer | a step of the dependency order | a wave, an apply batch built from layers |
| `/terragucci apply` | rerun `tf-apply` on a merged pull request, or an open one with `apply.when: pull-request`; gated waves still need an approval of their digest | Atlantis `apply`, which applies its stored plan; here each wave plans again |
| `/terragucci lock` | with `apply.when: pull-request` or `locks: plan`, lock the roots a pull request reaches without applying it | the lock Atlantis takes on every plan; under the default `locks: apply` a plan locks nothing, and with `locks: plan` the first plan locks |
| `/terragucci unlock` | with `apply.when: pull-request` or `locks: plan`, release the root locks a pull request took when it planned, applied or locked | Atlantis `unlock`, which also discards plans; none are kept here |
| run | a forge pipeline run, with its jobs | an HCP Terraform run, which is one plan and apply in one workspace |

---

# Control repo

Source: https://intentius.io/terragucci/concepts/control-repo/

Twenty repos with twenty pipelines drift apart: one runs an older binary, one skips the shared policy, one never got the drift schedule. A control repo keeps them alike without editing each one. You change one file, and every project that changes gets a pull request its own team merges.

A control repo is optional. One repo works on its own, with its own `terragucci.yml`; a control repo is for keeping many repos alike.

## Contents

The control repo's `terragucci.yml` lists the projects and what they share.

```yaml
defaults:
  binary: tofu
  policy:
    source: git+https://github.com/acme/policy.git@v3
projects:
  github.com/acme/infra:
    roots: ["envs/*/*"]
  gitlab.example.com/platform/network:
    drift: "17 4 * * *"
  codeberg.org/acme/edge: {}
```

| Key | Holds |
|---|---|
| `projects` | each repo by `<host>/<owner>/<name>` (a GitLab group path works too), with the keys that differ for it; a repo left out is never touched |
| `defaults` | the settings every project gets: any key but `url`, which names one repo, and `rollouts` |
| a project's `forge`, `url`, `token_env` | the forge of a host terragucci cannot name, a clone URL off https or the default port, the variable that holds its token |

A project's settings are terragucci's built-in defaults, then `defaults`, then the project's own keys. The maps `env`, `oidc`, `policy`, `waves`, `apply`, `respond`, `terragrunt` and `generate` merge key by key; every other key is replaced whole. `config check` refuses a top-level key outside `defaults` and `projects`, and `defaults` with no `projects`. [Keys](/terragucci/reference/config/#keys) lists each one, and [Manage the control repo with Terraform](/terragucci/guides/manage-the-control-repo-with-terraform/) writes the file with a provider instead.

## Reconcile

`terragucci reconcile` clones each project and writes its pipeline in the clone, as `init` would with the project's settings.

| Run | Result per project |
|---|---|
| `reconcile`, the preview | unchanged or would change, the files, and setup tips; nothing is written |
| `reconcile --mode apply` | for a project that changes, a commit on `terragucci/pipeline` and a pull request (a merge request on GitLab), opened or updated; an unchanged project gets none |

`--mode apply` never writes a default branch and runs no `terraform apply`. One project failing does not stop the others; the command names it and exits 1. A later run opens a pull request only where something changed.

The pull request carries:

| File | Holds |
|---|---|
| the pipeline file for the project's forge | the keys flags and the job carry, such as `binary`, `version`, `apply`, `locks`, `oidc`, `notify` |
| `terragucci.yml`, marked as written by `reconcile` | the keys the jobs read from the repo, such as `policy`, `reports`, `approval`, `gate`, `parallelism` |
| each root's backend, provider and version files | with [`generate`](/terragucci/guides/generate-root-files/#in-a-control-repo) set |

[A file for many repos](/terragucci/reference/config/#a-file-for-many-repos) sorts every key into the two ways.

## Project side

| Stays in each project | Detail |
|---|---|
| the roots, state and backend | `reconcile` writes only the files above |
| the merge | the project's team reviews and merges the pull request |
| plan, approvals and apply | the project's own pipeline runs them, and approvals land on its own [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) |
| its own `terragucci.yml` | kept; when a key the jobs read differs from the control repo's, `reconcile` fails that project and names the key |

`unlock-state` and `ephemeral` run in a project's checkout, never in the control repo.

## Across projects

| From the control repo | Does |
|---|---|
| `reconcile` | one pipeline pull request per project that changes |
| [`defaults.policy.source`](/terragucci/reference/policy/#from-a-control-repo) | one policy repo, at a pinned ref, for every project |
| [`rollout`](/terragucci/guides/roll-out-a-module-version/) | wave 1 holds every project's canaries, then each project in config order, a pull request per project per wave; `respond rollout --mode apply` on a schedule continues it |
| [`estate`](/terragucci/guides/see-every-project/) | one page from each project's own reports bucket, written under `defaults.reports` |
| [`audit`](/terragucci/reference/audit-trail/) | each project's approvals from its repo and its reports, in one record under `defaults.reports` |

## Mixed forges

One file can list projects on GitHub, GitLab and Forgejo. The host names the forge (`github.com`, `gitlab.com`, `codeberg.org`, and hosts starting `github.`, `gitlab.`, `forgejo.` or `gitea.`); set `forge` for any other. Each forge's token comes from `GITHUB_TOKEN`, `GITLAB_TOKEN` or `FORGEJO_TOKEN`, or the variable a project's `token_env` names.

## Fit

| You have | Use |
|---|---|
| one repo | its own `terragucci.yml` and `init`; `reconcile` refuses a file with no `projects` |
| several repos that should share a binary, policy, gates or reports | a control repo |
| a project that needs a different value | the key under that project, not `defaults` |
| a repo terragucci should not touch | leave it out of `projects` |

## Next

- [Govern many repos from one place](/terragucci/guides/govern-many-repos/) sets one up.
- [Manage the control repo with Terraform](/terragucci/guides/manage-the-control-repo-with-terraform/)

---

# Locking and staleness

Source: https://intentius.io/terragucci/concepts/locking-and-staleness/

Two changes can meet on one root at the same time. A plan can also stop matching: something else landed between the plan and its apply. Three tiers handle this.

## Backend state lock

Your backend gives one lock per state file, held while a binary writes it: an S3 backend with `use_lockfile`, a DynamoDB table, a GCS lock object, an Azure blob lease, GitLab-managed state. That is what a plain repo with a CI script, or a Terragrunt `run --all`, works with. It keeps two writers off one state file. It does not decide which change goes first, and it does not check that a plan still matches.

## terragucci layers

terragucci adds these on every binary and repo shape. Each works per root, or per Terragrunt unit, Atmos instance or Terramate stack, never per resource: one state file cannot take two writers.

### Pull request locks

Under `apply.when: pull-request` a pull request holds each root it reaches until it merges or closes; `/terragucci lock` takes the hold without applying. Another pull request that reaches a held root is refused with the holder named. With `locks: plan` the hold starts at the first plan. In a Terragrunt repo dependency blocks extend the reach; in an Atmos repo a stack manifest change reaches every instance; with `synth`, such as a CDK Terrain app, a change to the app reaches every stack. [Apply before merge](/terragucci/guides/apply-before-merge/#locks), [plan locks](/terragucci/reference/pipeline/#plan-locks).

### Applies kept apart

Two pushes that change different roots apply side by side. A root's own applies take turns at its state lock. A push's wave whose commit is no longer the branch tip stands down before it applies, and the newer push applies the whole tree. [Applies side by side](/terragucci/reference/pipeline/#applies-side-by-side).

### Stale plans

An approval covers the plan digest it was shown. A wave whose plans moved after the approval applies nothing and names the root that moved. A pull request behind the default branch is refused, and its plan note is marked stale once the default branch changes a root it planned; a re-plan brings it up to date. [Approval binding](/terragucci/concepts/waves-and-approvals/#approval-binding), [re-plan from a comment](/terragucci/guides/re-plan-from-a-comment/).

### Lock waits

Pull request plans and drift runs take no lock (`-lock=false`) and never wait for an apply. A wave's plan and apply wait up to five minutes for the state lock (`-lock-timeout=5m`); with Terraform and OpenTofu the wait shows in the root's plan time, and choudoufu on a backend that locks records each wait as a span and a metric. [State lock waits](/terragucci/reference/observability/#state-lock-waits).

### Releasing a state lock

A job killed mid-apply leaves its state lock held. `terragucci unlock-state` releases it only when no run that began before the lock is alive, after an approval of that lock's ID, and records who released it on `chant/lifecycle`. [Release a state lock](/terragucci/guides/release-a-state-lock/).

### Claims

A gap is a claim that has not run on that forge or binary yet.

## With choudoufu

`binary: choudoufu`, the OpenTofu fork from the team behind terragucci ([set it up](/terragucci/guides/use-a-binary/#choudoufu)), takes no state lock at all. Each resource is a record, and every write to it is conditional. Changes to different resources of one estate apply at the same time, an overlapping change waits (or is refused) before it reaches the cloud, and a plan made stale by another apply is refused. A killed apply leaves nothing to release, and keeps the records of what it finished.

Each row names the check that proves it: terragucci's on [Validation](/terragucci/reference/validation/), choudoufu's by claim number on its site.

### Two applies of one estate

| What the second wave meets | A push's wave | The apply a comment starts |
|---|---|---|
| a run applying other resources of the estate | applies beside it (`cdf-rows-overlap`) | the same |
| a run applying a resource it changes | waits for that run, then plans again and applies, with no call to the cloud while it waits (`cdf-rows-wait`) | refused at once; the reply names the run, and you comment `/terragucci apply` again once it is done |
| a run that was killed while applying it | takes over what that run held, with nothing to release; the apply re-reads the live system and refuses a plan the killed run made stale (`cdf-rows-takeover`), and what the killed run finished applying has its record (`cdf-killed-records`), so a gated wave applies the rest under the same approval ([Stopped applies](/terragucci/reference/pipeline/#stopped-applies), `cdf-resume`) | the same |

Once the gate lets a wave through, and before its apply re-reads the live system, the wave holds each resource its plans create, update, delete, replace or forget. Data reads and resources with no change hold nothing. A resource is keyed by its estate and address, by the address it moved from, and for an update or a delete by the live object's ID, so two estates that manage one object meet on it.

| | How |
|---|---|
| Where the wave keeps them | one file on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle), `_locks/apply-rows.json`, taken in one commit: all of the wave's resources or none |
| When it lets go | when the wave ends, applied or not |
| A run that is gone | its forge says the run ended, or its entry is two hours old (`TG_LOCK_STALE`): the next wave takes everything that run held over in the same commit |
| Plans | hold nothing, so every pull request plans at once |
| Pull request locks | stay per root ([plan locks](/terragucci/reference/pipeline/#plan-locks)) |

Only choudoufu applies this way. Holding a resource means something only when its apply writes that resource alone and checks its plan per resource:

| Two applies inside one root | choudoufu | Stock |
|---|---|---|
| Writes | one record per resource, each write conditional | one state file, so the second apply waits for the state lock |
| A plan another apply staled | refused only when one of its own changes moved | refused when anything in the root moved ("Saved plan is stale") |
| A killed apply's work | marked in each create call, and recorded when its apply returns, so the next run finds it | a resource created after the last state write is unknown to the next plan |

An apply that does not go through the pipeline, such as `choudoufu apply` on a laptop, holds nothing, so the pipeline cannot wait for it; [the table below](#stock-and-choudoufu) says how the two settle. To keep the pipeline the only writer, give the apply role a trust policy that only your CI's identity on the default branch can assume ([credentials](/terragucci/reference/pipeline/#credentials)), and no person that role. A role scoped to one estate by its ownership tag ([live resource markers](#live-resource-markers)) confines each pipeline to its own estate.

### Stock and choudoufu

Terraform and OpenTofu (stock) keep a state file behind a lock. choudoufu keeps an estate with a [record store](#record-writes).

| | Stock | choudoufu |
|---|---|---|
| A killed apply | the state lock stays held until [`terragucci unlock-state`](/terragucci/guides/release-a-state-lock/) frees it after an approval (`unlock-state`) | no lock is held, so there is nothing to release, and `force-unlock` refuses ([claim 2](https://intentius.io/choudoufu/docs/claims/no-self-managed-locks/)) |
| What a killed apply created | a resource created after the last state write is unknown to the next plan, and the re-run creates a second one ([claim 5](https://intentius.io/choudoufu/docs/claims/recovery-is-a-rerun/), its markers withheld) | a resource marked in its create call is named by the next plan and bound by the re-run, with no duplicate; a resource whose apply returned before the kill already has its record, so the next plan leaves it alone (`cdf-killed-records`); [claim 42](https://intentius.io/choudoufu/docs/claims/a-killed-apply-hides-nothing/) names the types marked only after their create |
| A stale saved plan | a wave applies only plans whose digest the approval covered (`audit-refused`) | the same, and the apply re-reads the live system: if one of the plan's changes moved in address, action, live object or value, it refuses and names it ([claim 15](https://intentius.io/choudoufu/docs/claims/apply-what-was-approved/)); for an attribute the cloud holds, such as a queue's visibility timeout, this re-read is what refuses the second of two saved plans ([an attribute the cloud holds](https://intentius.io/choudoufu/docs/model/concurrency/#an-attribute-the-cloud-holds)) |
| Two applies that meet outside the pipeline, such as a laptop and CI | the second waits for the state lock (`lock-wait`) | on different resources, both land and neither waits (`cdf-concurrency`): two waves that each add a resource taking 60 seconds finish both in under 90 (`cdf-concurrency-time`); on one record, one lands, the other fails naming it and overwrites nothing, and its re-plan shows the value that landed (`cdf-write-race`); on an attribute the cloud holds and no record keeps, two plain applies are last-writer-wins, and only applies of saved plans refuse ([an attribute the cloud holds](https://intentius.io/choudoufu/docs/model/concurrency/#an-attribute-the-cloud-holds)) |
| Ownership | the root's state file | a tag on each resource; a role scoped by the estate tag is refused on another estate's resources (`cdf-iam`); one bucket for every estate (`cdf-shared-bucket`) |
| Lock-wait metrics | with choudoufu as the binary, each wait is a `State lock wait` span in the report and `terragucci_lock_wait_seconds` (`lock-wait`) | none: no lock, and the report lists no waits (`cdf-concurrency`) |

A wave applies the plan file it saved, so claim 15's check runs inside the wave.

The state file is a cache: never the record of what you own, and losing it costs a refresh ([claim 5](https://intentius.io/choudoufu/docs/claims/recovery-is-a-rerun/)).

### Record writes

The estate's record store bucket holds one record per resource, and every write to it is one conditional S3 `PutObject`. The cloud's API therefore settles two runs that reach one resource:

| Record write | Condition | When another run got there first |
|---|---|---|
| create | `If-None-Match: *` | the write fails, because the record exists |
| update | `If-Match: <the version it read>` | the write fails, because the version moved |

### Live resource markers

Each resource carries its identity as tags. The create call writes them; for the few types whose create takes no tags, the next call does.

| Tag | Holds |
|---|---|
| `tofu-estate` | the estate that owns the resource |
| `tofu-address` | the resource's address in the configuration |

| What the tags give you | How |
|---|---|
| Each address finds its real resource | the next plan matches the address to the resource that carries it in its tags |
| An estate any cloud tool can list | filter on the tag, for example `aws ec2 describe-instances --filters Name=tag:tofu-estate,Values=prod` |
| A role scoped to one estate | an IAM condition on the tag: the role applies its own estate, and IAM refuses it a change to another estate's resources |

The scoped role's write statement, for an estate called `prod`:

```json
{
  "Effect": "Allow",
  "Action": ["ec2:CreateTags", "ec2:DeleteTags", "ec2:TerminateInstances"],
  "Resource": "*",
  "Condition": { "StringEquals": { "aws:ResourceTag/tofu-estate": "prod" } }
}
```

The role also reads with `ec2:Describe*`. [choudoufu's marker spec](https://github.com/INTENTIUS/choudoufu/blob/main/live/MARKERS.md) publishes the whole grant, creates included.

### One backend for all your estates

Values the cloud has nowhere to keep go in a record store: an S3 bucket you own. One bucket serves every estate, and each root names its estate and the bucket:

```hcl
terraform {
  live {
    estate = "prod-eu"

    record_store "s3" {
      bucket = "acme-records"
    }
  }
}
```

| In the shared bucket | What you get |
|---|---|
| `tofu-records/<estate>/` | each estate's records, one per resource, under a prefix of its own |
| the `tofu-estate` tag on each object | every record carries its estate's tag |
| estates whose names start alike, such as `prod` and `prod-eu` | no shared keys: each holds only its own records, and the next plan of both shows no change |

The apply checks the bucket before it writes a record:

| Bucket setting | Value |
|---|---|
| versioning | enabled |
| lifecycle | a rule that expires noncurrent versions |
| public access blocks | all four on |

[choudoufu's bucket page](https://intentius.io/choudoufu/docs/use/bucket/) has the IAM policy for a role per estate.

---

# Coding agents

Source: https://intentius.io/terragucci/for/agents/

Setup by an agent, and four opt-in features that run a model.

## Works

- An agent can run the setup and stops at a pull request; it never applies or approves
- A read-only MCP server over the estate, the audit trail and the delivery metrics, running no model
- Four opt-in features run a model, each off until you set it up with a model API key

## Differs

- On GitLab the agent comment and drift fixes are refused, and the review runs through the comments schedule.

## First step

[Set up with a coding agent](https://intentius.io/terragucci/getting-started/agents/)

## You can count on

- [A plan note on every pull request](https://intentius.io/terragucci/getting-started/)
- [Gated applies of the plans you approved](https://intentius.io/terragucci/guides/approve-a-wave/)
- [No overlapping or stale applies](https://intentius.io/terragucci/concepts/locking-and-staleness/)
- [Re-plan from a comment](https://intentius.io/terragucci/guides/re-plan-from-a-comment/)
- [Scheduled drift checks](https://intentius.io/terragucci/guides/turn-on-drift-checks/)
- [OIDC roles, one to plan, one to apply](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Policy on every plan](https://intentius.io/terragucci/guides/write-a-policy/)
- [An audit trail in your bucket](https://intentius.io/terragucci/guides/read-the-audit-trail/)
- [Secrets kept out of notes and logs](https://intentius.io/terragucci/guides/keep-secrets-out-of-notes/)
- [Your state backend, as is](https://intentius.io/terragucci/reference/state-backends/)
- [Your own runners](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Your forge's sign-in and permissions](https://intentius.io/terragucci/standards/access-and-identity/)

## Then read

Tasks: [Agent changes to a pull request](https://intentius.io/terragucci/guides/agent-change-a-pull-request/), [Agent drift fixes](https://intentius.io/terragucci/guides/agent-fix-drift/), [Model review of a pull request](https://intentius.io/terragucci/guides/agent-review-a-pull-request/), [Refused wave summaries](https://intentius.io/terragucci/guides/agent-refused-wave/), [The estate over MCP](https://intentius.io/terragucci/guides/agent-read-over-mcp/)

Background: [Architecture](https://intentius.io/terragucci/concepts/how-it-works/)

Details: [CLI commands](https://intentius.io/terragucci/reference/cli/)

---

# Atmos

Source: https://intentius.io/terragucci/for/atmos/

An Atmos repo, where each component instance is a root in its own workspace.

## Works

- Each component instance is a root, and dependencies.components decides the waves
- A pull request plans the instances it changes and the ones that depend on them
- The check job runs atmos validate stacks first

## Differs

- Settings that would edit an instance's copied directory are refused, each by name.
- A change outside a component directory, such as to a stack manifest, locks every instance.

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 Atmos](https://intentius.io/terragucci/guides/use-atmos/)

## Proof

10 recorded checks are proven for Atmos on Forgejo. The [validation page](https://intentius.io/terragucci/reference/validation/) lists them by feature area.

## You can count on

- [A plan note on every pull request](https://intentius.io/terragucci/getting-started/)
- [Gated applies of the plans you approved](https://intentius.io/terragucci/guides/approve-a-wave/)
- [No overlapping or stale applies](https://intentius.io/terragucci/concepts/locking-and-staleness/)
- [Re-plan from a comment](https://intentius.io/terragucci/guides/re-plan-from-a-comment/)
- [Scheduled drift checks](https://intentius.io/terragucci/guides/turn-on-drift-checks/)
- [OIDC roles, one to plan, one to apply](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Policy on every plan](https://intentius.io/terragucci/guides/write-a-policy/)
- [An audit trail in your bucket](https://intentius.io/terragucci/guides/read-the-audit-trail/)
- [Secrets kept out of notes and logs](https://intentius.io/terragucci/guides/keep-secrets-out-of-notes/)
- [Your state backend, as is](https://intentius.io/terragucci/reference/state-backends/)
- [Your own runners](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Your forge's sign-in and permissions](https://intentius.io/terragucci/standards/access-and-identity/)

## Then read

Tasks: [Use Atmos](https://intentius.io/terragucci/guides/use-atmos/)

Background: [Waves and approvals](https://intentius.io/terragucci/concepts/waves-and-approvals/)

Details: [terragucci.yml keys](https://intentius.io/terragucci/reference/config/)

---

# CDK Terrain

Source: https://intentius.io/terragucci/for/cdk-terrain/

A CDK Terrain app, synthesized in the pipeline before each plan.

## Works

- synth runs in the pipeline, then each pull request plans the stacks its change affects
- Each apply wave synthesizes the stacks and applies behind its gate
- A stack that reads another's state plans on that stack's planned outputs

## Differs

- The stacks are the app's output, so terragucci never edits them: drift goes to the issue, and rollouts and generate are config errors.
- A Terragrunt repo takes no synth, so the two do not mix.

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

[Plan CDK Terrain stacks](https://intentius.io/terragucci/guides/plan-cdk-terrain-stacks/)

## Proof

10 recorded checks are proven for CDK Terrain on Forgejo. The [validation page](https://intentius.io/terragucci/reference/validation/) lists them by feature area.

## You can count on

- [A plan note on every pull request](https://intentius.io/terragucci/getting-started/)
- [Gated applies of the plans you approved](https://intentius.io/terragucci/guides/approve-a-wave/)
- [No overlapping or stale applies](https://intentius.io/terragucci/concepts/locking-and-staleness/)
- [Re-plan from a comment](https://intentius.io/terragucci/guides/re-plan-from-a-comment/)
- [Scheduled drift checks](https://intentius.io/terragucci/guides/turn-on-drift-checks/)
- [OIDC roles, one to plan, one to apply](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Policy on every plan](https://intentius.io/terragucci/guides/write-a-policy/)
- [An audit trail in your bucket](https://intentius.io/terragucci/guides/read-the-audit-trail/)
- [Secrets kept out of notes and logs](https://intentius.io/terragucci/guides/keep-secrets-out-of-notes/)
- [Your state backend, as is](https://intentius.io/terragucci/reference/state-backends/)
- [Your own runners](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Your forge's sign-in and permissions](https://intentius.io/terragucci/standards/access-and-identity/)

## Then read

Tasks: [Plan CDK Terrain stacks](https://intentius.io/terragucci/guides/plan-cdk-terrain-stacks/)

Background: [Waves and approvals](https://intentius.io/terragucci/concepts/waves-and-approvals/)

Details: [terragucci.yml keys](https://intentius.io/terragucci/reference/config/)

---

# choudoufu

Source: https://intentius.io/terragucci/for/choudoufu/

The OpenTofu fork from the team behind terragucci, set with binary: choudoufu.

## Works

- One record per resource in an S3 bucket you own, each write conditional, with no lock table
- Applies to different resources of one estate run at the same time; a killed apply leaves nothing to release
- A live check on every push, and the slowest provider calls in the report

## Differs

- terragucci does not read a root's required_version as a choudoufu release.
- Record history needs the ListBucketVersions permission on the record store bucket; a local or kubernetes record store keeps none.

## First step

[Choose your binary: choudoufu](https://intentius.io/terragucci/guides/use-a-binary/#choudoufu)

## Proof

35 recorded checks are proven for choudoufu on Forgejo. The [validation page](https://intentius.io/terragucci/reference/validation/) lists them by feature area.

## You can count on

- [A plan note on every pull request](https://intentius.io/terragucci/getting-started/)
- [Gated applies of the plans you approved](https://intentius.io/terragucci/guides/approve-a-wave/)
- [No overlapping or stale applies](https://intentius.io/terragucci/concepts/locking-and-staleness/)
- [Re-plan from a comment](https://intentius.io/terragucci/guides/re-plan-from-a-comment/)
- [Scheduled drift checks](https://intentius.io/terragucci/guides/turn-on-drift-checks/)
- [OIDC roles, one to plan, one to apply](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Policy on every plan](https://intentius.io/terragucci/guides/write-a-policy/)
- [An audit trail in your bucket](https://intentius.io/terragucci/guides/read-the-audit-trail/)
- [Secrets kept out of notes and logs](https://intentius.io/terragucci/guides/keep-secrets-out-of-notes/)
- [Your state backend, as is](https://intentius.io/terragucci/reference/state-backends/)
- [Your own runners](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Your forge's sign-in and permissions](https://intentius.io/terragucci/standards/access-and-identity/)

## Then read

Tasks: [Choose your binary](https://intentius.io/terragucci/guides/use-a-binary/), [Watch a choudoufu wave](https://intentius.io/terragucci/guides/watch-a-choudoufu-wave/)

Background: [Locking with choudoufu](https://intentius.io/terragucci/concepts/locking-and-staleness/#with-choudoufu)

Details: [Traces and metrics](https://intentius.io/terragucci/reference/observability/)

---

# Evaluation

Source: https://intentius.io/terragucci/for/evaluate/

What terragucci does and proves, and what it leaves to your forge and your cloud.

## Works

- Apache-2.0, with nothing to buy and no server to host
- Every pipeline feature that runs on Forgejo is proven by a recorded check, listed by tool and forge
- Scored against the 24 tacos.guru criteria

## Differs

Nothing beyond what the other pages describe.

## First step

[See a plan note in about 10 minutes](https://intentius.io/terragucci/tutorial/)

## You can count on

- [A plan note on every pull request](https://intentius.io/terragucci/getting-started/)
- [Gated applies of the plans you approved](https://intentius.io/terragucci/guides/approve-a-wave/)
- [No overlapping or stale applies](https://intentius.io/terragucci/concepts/locking-and-staleness/)
- [Re-plan from a comment](https://intentius.io/terragucci/guides/re-plan-from-a-comment/)
- [Scheduled drift checks](https://intentius.io/terragucci/guides/turn-on-drift-checks/)
- [OIDC roles, one to plan, one to apply](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Policy on every plan](https://intentius.io/terragucci/guides/write-a-policy/)
- [An audit trail in your bucket](https://intentius.io/terragucci/guides/read-the-audit-trail/)
- [Secrets kept out of notes and logs](https://intentius.io/terragucci/guides/keep-secrets-out-of-notes/)
- [Your state backend, as is](https://intentius.io/terragucci/reference/state-backends/)
- [Your own runners](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Your forge's sign-in and permissions](https://intentius.io/terragucci/standards/access-and-identity/)

## Then read

Tasks: [Add terragucci to a repo](https://intentius.io/terragucci/guides/add-to-a-repo/)

Background: [Architecture](https://intentius.io/terragucci/concepts/how-it-works/), [tacos.guru](https://intentius.io/terragucci/standards/tacos-guru/)

Details: [Validation](https://intentius.io/terragucci/reference/validation/), [Scale](https://intentius.io/terragucci/reference/scale/)

---

# Many repos

Source: https://intentius.io/terragucci/for/many-repos/

One place that keeps every repo's settings and policy alike.

## Works

- A control repo holds the shared settings and opens a pull request in each repo that changes
- A single project works without a control repo, from its own terragucci.yml
- One estate page lists every project with its roots and last applies
- A new module version rolls out to every repo that pins it, a wave of pull requests at a time

## Differs

Nothing beyond what the other pages describe.

## First step

[Govern many repos](https://intentius.io/terragucci/guides/govern-many-repos/)

## You can count on

- [A plan note on every pull request](https://intentius.io/terragucci/getting-started/)
- [Gated applies of the plans you approved](https://intentius.io/terragucci/guides/approve-a-wave/)
- [No overlapping or stale applies](https://intentius.io/terragucci/concepts/locking-and-staleness/)
- [Re-plan from a comment](https://intentius.io/terragucci/guides/re-plan-from-a-comment/)
- [Scheduled drift checks](https://intentius.io/terragucci/guides/turn-on-drift-checks/)
- [OIDC roles, one to plan, one to apply](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Policy on every plan](https://intentius.io/terragucci/guides/write-a-policy/)
- [An audit trail in your bucket](https://intentius.io/terragucci/guides/read-the-audit-trail/)
- [Secrets kept out of notes and logs](https://intentius.io/terragucci/guides/keep-secrets-out-of-notes/)
- [Your state backend, as is](https://intentius.io/terragucci/reference/state-backends/)
- [Your own runners](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Your forge's sign-in and permissions](https://intentius.io/terragucci/standards/access-and-identity/)

## Then read

Tasks: [Govern many repos](https://intentius.io/terragucci/guides/govern-many-repos/), [Control repo in Terraform](https://intentius.io/terragucci/guides/manage-the-control-repo-with-terraform/), [Every project, one page](https://intentius.io/terragucci/guides/see-every-project/), [Roll out a module](https://intentius.io/terragucci/guides/roll-out-a-module-version/)

Background: [Control repo](https://intentius.io/terragucci/concepts/control-repo/)

Details: [terragucci.yml keys](https://intentius.io/terragucci/reference/config/)

---

# Terraform or OpenTofu roots

Source: https://intentius.io/terragucci/for/plain-roots/

Directories of .tf files with their own state.

## Works

- init finds every root and writes the pipeline for your forge
- Each root runs its own pinned Terraform or OpenTofu version
- Roots that read each other through terraform_remote_state apply in waves, in order

## Differs

Nothing beyond what the other pages describe.

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

[Get your first plan note](https://intentius.io/terragucci/getting-started/)

## Proof

276 recorded checks are proven for OpenTofu on Forgejo. The [validation page](https://intentius.io/terragucci/reference/validation/) lists them by feature area.

## You can count on

- [A plan note on every pull request](https://intentius.io/terragucci/getting-started/)
- [Gated applies of the plans you approved](https://intentius.io/terragucci/guides/approve-a-wave/)
- [No overlapping or stale applies](https://intentius.io/terragucci/concepts/locking-and-staleness/)
- [Re-plan from a comment](https://intentius.io/terragucci/guides/re-plan-from-a-comment/)
- [Scheduled drift checks](https://intentius.io/terragucci/guides/turn-on-drift-checks/)
- [OIDC roles, one to plan, one to apply](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Policy on every plan](https://intentius.io/terragucci/guides/write-a-policy/)
- [An audit trail in your bucket](https://intentius.io/terragucci/guides/read-the-audit-trail/)
- [Secrets kept out of notes and logs](https://intentius.io/terragucci/guides/keep-secrets-out-of-notes/)
- [Your state backend, as is](https://intentius.io/terragucci/reference/state-backends/)
- [Your own runners](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Your forge's sign-in and permissions](https://intentius.io/terragucci/standards/access-and-identity/)

## Then read

Tasks: [Add terragucci to a repo](https://intentius.io/terragucci/guides/add-to-a-repo/), [Choose your binary](https://intentius.io/terragucci/guides/use-a-binary/), [Approve a waiting wave](https://intentius.io/terragucci/guides/approve-a-wave/)

Background: [Architecture](https://intentius.io/terragucci/concepts/how-it-works/), [Waves and approvals](https://intentius.io/terragucci/concepts/waves-and-approvals/)

Details: [terragucci.yml keys](https://intentius.io/terragucci/reference/config/), [Stages](https://intentius.io/terragucci/reference/stages/)

---

# Security review

Source: https://intentius.io/terragucci/for/security/

What each job can reach and who can approve, with the record every change leaves.

## Works

- Plan and apply use separate roles, and the plan job never gets the apply role
- A gated wave whose plans moved after the approval applies nothing and names both digests
- The audit trail in your bucket records every approval, apply and override

## Differs

- terragucci has no accounts; access and identity maps each action to the forge or IAM setting that decides it.

## First step

[The threat model](https://intentius.io/terragucci/reference/threat-model/)

## You can count on

- [A plan note on every pull request](https://intentius.io/terragucci/getting-started/)
- [Gated applies of the plans you approved](https://intentius.io/terragucci/guides/approve-a-wave/)
- [No overlapping or stale applies](https://intentius.io/terragucci/concepts/locking-and-staleness/)
- [Re-plan from a comment](https://intentius.io/terragucci/guides/re-plan-from-a-comment/)
- [Scheduled drift checks](https://intentius.io/terragucci/guides/turn-on-drift-checks/)
- [OIDC roles, one to plan, one to apply](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Policy on every plan](https://intentius.io/terragucci/guides/write-a-policy/)
- [An audit trail in your bucket](https://intentius.io/terragucci/guides/read-the-audit-trail/)
- [Secrets kept out of notes and logs](https://intentius.io/terragucci/guides/keep-secrets-out-of-notes/)
- [Your state backend, as is](https://intentius.io/terragucci/reference/state-backends/)
- [Your own runners](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Your forge's sign-in and permissions](https://intentius.io/terragucci/standards/access-and-identity/)

## Then read

Tasks: [Write a policy](https://intentius.io/terragucci/guides/write-a-policy/), [Read the audit trail](https://intentius.io/terragucci/guides/read-the-audit-trail/), [Lock roots](https://intentius.io/terragucci/guides/lock-roots/), [Secrets out of notes](https://intentius.io/terragucci/guides/keep-secrets-out-of-notes/), [Scope state access](https://intentius.io/terragucci/guides/scope-state-access/), [Approvals runbook](https://intentius.io/terragucci/guides/approvals-runbook/)

Background: [Approvals as records](https://intentius.io/terragucci/concepts/approvals-as-records/), [Access and identity](https://intentius.io/terragucci/standards/access-and-identity/)

Details: [Threat model](https://intentius.io/terragucci/reference/threat-model/), [Policy](https://intentius.io/terragucci/reference/policy/), [The audit trail](https://intentius.io/terragucci/reference/audit-trail/), [Validation](https://intentius.io/terragucci/reference/validation/)

---

# Terragrunt

Source: https://intentius.io/terragucci/for/terragrunt/

A Terragrunt repo of units or explicit stacks, or one on Terragrunt Scale.

## Works

- Each unit is a root, and dependency order decides the waves
- A pull request plans the units of every layer it reaches, each on its upstream's planned outputs
- terragucci import terragrunt-scale reads Gruntwork Pipelines' environments and roles

## Differs

- roots is refused; terragrunt.exclude leaves units out.
- A step after init is refused, since Terragrunt inits each unit inside the plan.
- CDK Terrain in a Terragrunt repo is not supported.

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 Terragrunt](https://intentius.io/terragucci/guides/use-terragrunt/)

## Proof

48 recorded checks are proven for Terragrunt on Forgejo. The [validation page](https://intentius.io/terragucci/reference/validation/) lists them by feature area.

## You can count on

- [A plan note on every pull request](https://intentius.io/terragucci/getting-started/)
- [Gated applies of the plans you approved](https://intentius.io/terragucci/guides/approve-a-wave/)
- [No overlapping or stale applies](https://intentius.io/terragucci/concepts/locking-and-staleness/)
- [Re-plan from a comment](https://intentius.io/terragucci/guides/re-plan-from-a-comment/)
- [Scheduled drift checks](https://intentius.io/terragucci/guides/turn-on-drift-checks/)
- [OIDC roles, one to plan, one to apply](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Policy on every plan](https://intentius.io/terragucci/guides/write-a-policy/)
- [An audit trail in your bucket](https://intentius.io/terragucci/guides/read-the-audit-trail/)
- [Secrets kept out of notes and logs](https://intentius.io/terragucci/guides/keep-secrets-out-of-notes/)
- [Your state backend, as is](https://intentius.io/terragucci/reference/state-backends/)
- [Your own runners](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Your forge's sign-in and permissions](https://intentius.io/terragucci/standards/access-and-identity/)

## Then read

Tasks: [Use Terragrunt](https://intentius.io/terragucci/guides/use-terragrunt/), [From Terragrunt Scale](https://intentius.io/terragucci/guides/use-terragrunt/#terragrunt-scale), [Steps around a stage](https://intentius.io/terragucci/guides/run-steps/)

Background: [Waves and approvals](https://intentius.io/terragucci/concepts/waves-and-approvals/)

Details: [terragucci.yml keys](https://intentius.io/terragucci/reference/config/)

---

# Terramate

Source: https://intentius.io/terragucci/for/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:

- 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](https://intentius.io/terragucci/guides/use-terramate/)

## Proof

5 recorded checks are proven for Terramate on Forgejo. The [validation page](https://intentius.io/terragucci/reference/validation/) lists them by feature area.

## You can count on

- [A plan note on every pull request](https://intentius.io/terragucci/getting-started/)
- [Gated applies of the plans you approved](https://intentius.io/terragucci/guides/approve-a-wave/)
- [No overlapping or stale applies](https://intentius.io/terragucci/concepts/locking-and-staleness/)
- [Re-plan from a comment](https://intentius.io/terragucci/guides/re-plan-from-a-comment/)
- [Scheduled drift checks](https://intentius.io/terragucci/guides/turn-on-drift-checks/)
- [OIDC roles, one to plan, one to apply](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Policy on every plan](https://intentius.io/terragucci/guides/write-a-policy/)
- [An audit trail in your bucket](https://intentius.io/terragucci/guides/read-the-audit-trail/)
- [Secrets kept out of notes and logs](https://intentius.io/terragucci/guides/keep-secrets-out-of-notes/)
- [Your state backend, as is](https://intentius.io/terragucci/reference/state-backends/)
- [Your own runners](https://intentius.io/terragucci/guides/add-to-a-repo/)
- [Your forge's sign-in and permissions](https://intentius.io/terragucci/standards/access-and-identity/)

## Then read

Tasks: [Use Terramate](https://intentius.io/terragucci/guides/use-terramate/)

Background: [Waves and approvals](https://intentius.io/terragucci/concepts/waves-and-approvals/)

Details: [terragucci.yml keys](https://intentius.io/terragucci/reference/config/)

---

# Have an agent fix drift

Source: https://intentius.io/terragucci/guides/agent-fix-drift/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/agent-fix-drift/.
Add the `agent.drift` block and `respond.drift: off` to terragucci.yml, run `npx terragucci config check` and `npx terragucci init`, and open a pull request with the result.
List the machine user, token scopes and secrets I must set; do not create tokens or secrets yourself.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

One of the features that run a model ([what needs an agent](/terragucci/#opt-in-coding-agent)), off unless `agent.drift` is set.

## Result

When a [drift run](/terragucci/guides/turn-on-drift-checks/) opens the drift issue, a coding agent reads what drifted and changes the code to describe what is live. terragucci opens a pull request with the change and links it on the issue:

```text
terragucci: the drift agent opened https://forgejo.example/acme/infra/pulls/2, changing `app/main.tf`.
It plans like any other pull request; nothing was applied, approved or merged.
```

Merging the pull request keeps the change made outside the code, and its apply goes through the gate. Closing it and applying the code as it is undoes the drift instead.

## Prerequisites

| You need | Why |
|---|---|
| [Drift checks](/terragucci/guides/turn-on-drift-checks/) on GitHub or Forgejo | the agent runs when the drift job opens the drift issue; `init` refuses `agent.drift` on GitLab |
| An Anthropic API key in your forge's secrets | the default command runs Claude Code |
| A token for the pull request in your forge's secrets (step 1) | a pull request opened with the job's own token starts no workflow run, so it would not be planned |

## Steps

1. Make the agent's token. Keep it in a secret such as `AGENT_FORGE_TOKEN`, and the model's key in `ANTHROPIC_API_KEY`. It is the same token, with the same settings, as the [agent comment's](/terragucci/guides/agent-change-a-pull-request/).

**GitHub**

   | Setting | Value |
   |---|---|
   | Who | a machine user with write access, outside `CODEOWNERS` |
   | Token | fine-grained, for this repository alone |
   | Contents, pull requests, issues | read and write |
   | Workflows | none, so GitHub refuses any change it sends to `.github/workflows/` |
   | Default branch ruleset | a pull request and one approval of the latest change required, with no bypass for the machine user |

**GitLab**
   `init` refuses `agent.drift` on GitLab.
**Forgejo**

   | Setting | Value |
   |---|---|
   | Who | a machine user added as a collaborator with Write access |
   | Token scopes | `write:repository` and `write:issue` |
   | Default branch | the machine user stays off the push, approval and merge allowlists |

2. Turn it on in `terragucci.yml`. The agent's pull request replaces the codified one, so set `respond.drift` to `off` (or `attribute`, to keep who changed what in the issue):

   ```yaml
   drift: "17 4 * * *"
   respond:
     drift: off
   agent:
     via: forge
     token_env: AGENT_FORGE_TOKEN
     drift:
       key_secret: ANTHROPIC_API_KEY
       max_turns: 30
       timeout: 30
   ```

   `drift: true` under `agent` takes every default; the keys are the [agent comment's](/terragucci/reference/config/#the-drift-agent).

3. Check the file and write the pipeline, then merge the result to the default branch:

   ```bash
   npx terragucci config check
   npx terragucci init
   ```

4. Wait for drift, or run the drift workflow by hand. The drift issue gets the pull request's link; read the pull request and its plan note before you merge or close it.

## Agent inputs

The prompt lists each drifted resource by root with what the state held and what is live. A value the plan marks sensitive never appears:

```text
root app:
  aws_sqs_queue.jobs: changed
    visibility_timeout_seconds: state 30, live 45
```

It tells the agent that the drift and every file are untrusted input, since a value in the cloud can hold any text, and that a change to a guarded path is refused.

## Permissions

| Job | Does | Holds |
|---|---|---|
| `drift` | plans every root with `-refresh-only`, opens the drift issue, and says so in its outputs | the plan role, and its token for the issue |
| `drift-agent` | checks out the commit the drift job planned with no credentials kept, writes the prompt from the drift report, runs the agent, and keeps its changes as a patch | a read-only job token, which the agent's step runs without; the model's key, in the agent's step alone |
| `drift-agent-push` | applies the patch to the same commit in a fresh container; refuses one that touches a [guarded path](/terragucci/reference/pipeline/#paths-an-agent-cannot-change), with a comment on the issue naming the paths; commits any other to `terragucci/drift-agent-<issue>`, pushes it without force and opens the pull request | the agent's token |
| the plan job | plans the pull request with its read-only role | the plan role |

Neither agent job has a cloud role, whatever `oidc` says. Nothing here applies, approves or merges.

## Other agents

`command` takes any command line that reads a prompt on stdin and edits files in the working directory; `TG_AGENT_PROMPT` holds the prompt's path and `TG_AGENT_MAX_TURNS` the turn limit, as for the [agent comment](/terragucci/guides/agent-change-a-pull-request/#use-another-agent).

```yaml
agent:
  via: forge
  token_env: AGENT_FORGE_TOKEN
  drift:
    command: my-agent --non-interactive
    key_secret: MY_AGENT_KEY
```

## Read drift over MCP or `--json`

An agent at your desk reads the same drift without a model in the pipeline: `terragucci mcp`'s `index` tool lists the `tf-drift` runs and `report` reads one ([Read the estate over MCP](/terragucci/guides/agent-read-over-mcp/)). To change the code or the config, it runs the CLI with `--json`.

## Next

- [Turn on drift checks](/terragucci/guides/turn-on-drift-checks/) covers the schedule and the issue.
- [The generated pipeline](/terragucci/reference/pipeline/#the-drift-agent) lists the jobs and their tokens.

---

# Read the estate over MCP

Source: https://intentius.io/terragucci/guides/agent-read-over-mcp/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/agent-read-over-mcp/.
Tell me the command line and the environment variables to add terragucci mcp to my MCP client for this repo's reports bucket; do not add it yourself, and do not create or print credentials.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

`terragucci mcp` is a read-only Model Context Protocol server on stdio. It serves only what terragucci already wrote to the [reports bucket](/terragucci/guides/keep-reports-in-a-bucket/) and the repo, and runs no model of its own.

## Result

An agent that answers "when did `envs/prod/app` last apply, and what did it change?" from the bucket:

```json
{
  "project": "github.com/acme/infra",
  "root": "envs/prod/app",
  "commit": "ef7f8e50010c12dca8e20ecf90009638a8497f0d",
  "wave": 1,
  "approval": "approved",
  "applied": true,
  "report": "github.com/acme/infra/2026/10/ef7f8e50010c12dca8e20ecf90009638a8497f0d/tf-apply-wave-1",
  "result": { "path": "envs/prod/app", "status": "planned", "changes": [{ "address": "terraform_data.app", "action": "create" }] }
}
```

## Prerequisites

| You need | Why |
|---|---|
| [`reports.bucket`](/terragucci/guides/keep-reports-in-a-bucket/) set, and a pipeline that has run | the server reads the reports the stages copied there |
| `terragucci estate` and `terragucci audit` run on a schedule, for the `estate`, `dora` and `audit` tools | the server serves the files they write, and computes nothing |
| Read access to the bucket, in the environment the client starts the server from | the server takes credentials from its own environment, never from the agent |

## Steps

1. Give the server an identity that can read the bucket and nothing more, in the variables [Reports](/terragucci/reference/environment/#reports) lists.

   | Store | Identity |
   |---|---|
   | S3 | `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, or a role |
   | GCS | `GOOGLE_APPLICATION_CREDENTIALS` |
   | Azure Blob | `AZURE_STORAGE_KEY`, or an Entra ID identity |

2. Add the server to your MCP client. From the repo's root, where it reads `terragucci.yml`, the command line is:

   ```bash
   npx -y @intentius/terragucci mcp
   ```

   Outside the repo, name the bucket instead:

   ```bash
   npx -y @intentius/terragucci mcp --bucket s3://acme-plan-reports --bucket-prefix terragucci
   ```

   A client starts a stdio server with only a few variables of its own, so name the bucket's credentials in the server's `env`. A client that expands variables in its config, such as Claude Code's `.mcp.json`, keeps the values in your shell:

   ```json
   {
     "mcpServers": {
       "terragucci": {
         "command": "npx",
         "args": ["-y", "@intentius/terragucci", "mcp"],
         "env": {
           "AWS_ACCESS_KEY_ID": "${AWS_ACCESS_KEY_ID}",
           "AWS_SECRET_ACCESS_KEY": "${AWS_SECRET_ACCESS_KEY}",
           "AWS_REGION": "us-east-1"
         }
       }
     }
   }
   ```

3. Ask. The agent lists the tools and calls them:

   | Ask | Tool |
   |---|---|
   | when did a root last apply, and what changed | `last_apply` |
   | which runs ran on a commit, and their reports | `index`, then `report` |
   | where each wave of an applied commit stands | `run_view` |
   | which state version to restore | `state_versions` |
   | who approved what | `audit` |
   | how often you deploy, and how fast you restore | `dora` |
   | which wave waits, and the command to approve it | `waiting` |

## Refusals

| A call | The answer |
|---|---|
| `approve`, `apply`, `override`, or any tool it does not list | an error: approvals belong to a person at a shell, and an approval made over MCP is refused |
| an argument the tool does not list, such as `token` | an error; credentials come from the server's environment |
| a `report` path outside the bucket's prefix | an error |

The `waiting` tool prints each waiting wave's `terragucci approve` command for a person to run; the server cannot run it. [CLI commands](/terragucci/reference/cli/#mcp) lists each tool's arguments.

## MCP or `--json`

| You want to | Use |
|---|---|
| read what terragucci wrote: reports, the estate, state versions, the audit trail, DORA figures | `terragucci mcp` |
| set terragucci up, check a config, write the pipeline, plan, run a response in dry run | the CLI with `--json` ([JSON output](/terragucci/reference/cli-json/)) |
| approve, apply, override or merge | neither: a person does it |

## Next

- [Set up with a coding agent](/terragucci/getting-started/agents/) gives the agent's rules.
- [See every project](/terragucci/guides/see-every-project/) writes the estate page the `estate` tool reads.

---

# Approve from Slack and Teams

Source: https://intentius.io/terragucci/guides/approve-from-chat/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/approve-from-chat/.
Add `relay: terragucci` under `notify:` in terragucci.yml, and `apply.resume` if it is missing, run `npx terragucci config check` and `npx terragucci init`, and open a pull request.
Tell me which chat ids each approver needs on their line, and which token, secrets and Slack or Teams settings I must create; do not edit the signers file yourself, and do not create a token, a secret, a Slack app or a Teams webhook.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

A waiting wave's Slack message has an Approve and a Decline button. A Teams card gives the approving reply, `@terragucci approve wave-2 <digest>`, since Teams sends card buttons only to a registered bot. Clicks and replies go to `terragucci relay`, which you run in your own cloud; terragucci hosts nothing.

| A click by | Under `approval: ledger` or `pr-review` | Under `approval: sealed` |
|---|---|---|
| a chat user the signers file lists beside their principal | the relay records an approval of the digest the message showed, as that principal and marked relayed, and says so in the thread; the resume job applies the wave | refused: only the approver's own key seals an approval, so they run `terragucci approve --sign` |
| a chat user no line lists | refused in the thread; nothing is recorded | the same |
| anyone, after the plans moved | refused, naming the digest waiting now; nothing is recorded | the same |

Decline records nothing; the relay names who declined in the thread, and the wave waits until someone approves its plans.

## Prerequisites

| You need | Why |
|---|---|
| [Chat notices](/terragucci/guides/notify-a-chat-channel/) for the channel | the buttons go on those messages |
| [`apply.resume`](/terragucci/reference/pipeline/#resume-after-an-approval) | the relay starts no job, so the resume job applies the wave once the approval stands |
| A signers file, `.chant/allowed_signers`, on the default branch | the relay maps a chat user to a principal there |
| A place to run a container, or a function | the relay runs in your cloud |

## Steps

1. Add each approver's chat ids beside the principal on their line of `.chant/allowed_signers`, then merge the change. The relay reads the file on the default branch for every click.

   ```text
   alice@acme.com,slack:T0123ABCD/U0456EFGH,teams:6f1c2d0e-1a2b-4c3d-8e9f-0a1b2c3d4e5f ssh-ed25519 AAAAC3Nz...
   ```

   | Chat | The id | Where to find it |
   |---|---|---|
   | Slack | `slack:<team id>/<user id>` | the user's profile, Copy member ID; the workspace's team id is in its settings |
   | Teams | `teams:<Entra object id>` | the user's Object ID in Microsoft Entra |

   The approval records the line's first principal that is not a chat id. A chat id listed on two people's lines maps to neither.

2. Make the relay's token. It is approve-only: the relay refuses to start with a token that can do more than read the repo and push [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle).

**GitHub**
       A fine-grained token for this repo alone, with Contents: Read and write and nothing else, from an account that does not administer the repo. The relay refuses a classic token, and the default branch must be protected.
**GitLab**
       A project access token with the Developer role and the `write_repository` and `read_api` scopes. The default branch must be protected with push allowed to Maintainers or no one, and `chant/lifecycle` protected with push for Developers.
**Forgejo**
       A user with write access to the repo, and a token of theirs scoped `write:repository` and `read:user`. Protect the default branch so that user may not push to it.

3. Set up the chat side.

**Slack**
       Turn on Interactivity in the Slack app that holds the channel's incoming webhook, and set its Request URL to `<relay address>/slack`. Copy the app's Signing Secret.
**Teams**
       Add an outgoing webhook named `terragucci` to the team, with `<relay address>/teams` as its callback URL. Teams shows its security token once; copy it.

4. Run the relay. It reads its settings from [its environment](/terragucci/reference/environment/#the-relay).

**Container**
       Any container platform, such as ECS, Cloud Run, Azure Container Apps or Kubernetes, behind HTTPS:

       ```bash
       docker run -p 8080:8080 \
         -e TERRAGUCCI_RELAY_REPO=https://github.com/acme/infra.git \
         -e TERRAGUCCI_RELAY_TOKEN -e SLACK_SIGNING_SECRET -e TEAMS_WEBHOOK_SECRET \
         ghcr.io/intentius/terragucci-tofu:<the tag init names> terragucci relay
       ```
**Function**
       An AWS Lambda function built from a container image and reached through a function URL. The [Lambda Web Adapter](https://github.com/aws/aws-lambda-web-adapter) 1.1.0 extension passes each request to the same server, once `/healthz` answers:

       ```dockerfile
       FROM ghcr.io/intentius/terragucci-tofu:<the tag init names>
       COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:1.1.0 /lambda-adapter /opt/extensions/lambda-adapter
       ENV PORT=8080
       ENV AWS_LWA_READINESS_CHECK_PATH=/healthz
       CMD ["terragucci", "relay"]
       ```

       The adapter reads `PORT` when `AWS_LWA_PORT` is unset, and the relay serves on it. Give the function a timeout of 30 seconds or more: each cold start fetches the repo before the first request.

       Keep the token and the secrets in Secrets Manager and pass them to the function's environment.

   The startup log names the repo and default branch, then the user the relay pushes as. A token that can do more than approve stops the relay there, and the log gives the reason.

5. Set `notify.relay` in `terragucci.yml` and regenerate the pipeline, then merge:

   ```yaml
   apply:
     resume: 5
   notify:
     slack: SLACK_WEBHOOK_URL
     relay: terragucci
   ```

   ```bash
   npx terragucci init
   ```

   `relay` is the outgoing webhook's name in Teams, not a secret. The next waiting wave's message carries the buttons.

## Relay checks

| Check | Refused when |
|---|---|
| The request's signature: Slack's signing secret over the timestamp and body, or the Teams outgoing webhook's HMAC over the body | it does not verify, or a Slack request is more than five minutes old (401) |
| The chat user | no line of the signers file on the default branch lists them |
| The mode | the default branch's `approval` is `sealed` |
| The digest | no wave waits for the digest the button or reply names |

Slack waits three seconds for the relay to answer a click. If fetching the repo and pushing the approval take longer, Slack shows a timeout, but the thread reply still says what was recorded.

The approval line carries `relayedBy` and `via: slack` or `via: teams`, and the [audit trail](/terragucci/reference/audit-trail/) shows who relayed it. The [threat model](/terragucci/reference/threat-model/#the-chat-relay) says what the relay is trusted with.

## Next

- [Approve a waiting wave](/terragucci/guides/approve-a-wave/) from a checkout
- [Tell a chat channel when a wave stops](/terragucci/guides/notify-a-chat-channel/)

---

# Coming from Atlantis or OpenTaco

Source: https://intentius.io/terragucci/guides/coming-from-atlantis-or-opentaco/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/coming-from-atlantis-or-opentaco/.
Run `npx terragucci import atlantis --dry-run` (or `import digger --dry-run` for a digger.yml) and report what it would write and each setting it lists as not mapped or left out on purpose.
Then run it without --dry-run, run `npx terragucci config check --json` and `npx terragucci init`, and open a pull request with terragucci.yml and the generated pipeline.
Do not delete atlantis.yaml or digger.yml, and do not create secrets.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

A `terragucci.yml` that matches your Atlantis or OpenTaco setup, and jobs `init` writes for your forge's CI. There is no server and no account; the jobs write to your git and bucket.

## Import the settings

```bash
npx terragucci import atlantis   # reads atlantis.yaml
npx terragucci import digger     # reads digger.yml
npx terragucci init
```

[`import`](/terragucci/reference/cli/#import) writes `terragucci.yml` by the [settings table](#settings) below and prints each setting as one of:

- written as a key
- done with no key
- not mapped, and why
- [left out on purpose](#left-out-on-purpose), with the rule and what to do instead

The projects' directories become `roots`, so the generated pipeline plans the same projects. `--dry-run` prints it all and writes nothing.

Atlantis and OpenTaco apply before merge, so the import writes `apply.when: pull-request` and takes `apply.requires` from the projects' `apply_requirements`. `--apply-when merge` keeps terragucci's default. On GitLab it keeps `apply.when: merge` and says why: applying before merge there needs [`comments:` and a merge token](/terragucci/reference/config/#apply-before-merge-on-gitlab).

A project's `depends_on` is read against the repo. A dependency the roots' `terraform_remote_state` reads already give needs no key. The rest go into [`waves.after`](/terragucci/reference/config/#root-order), each root after the roots it depends on, named by its `dir`. A cycle that `depends_on` and the reads make together is listed as not mapped, and no order is written.

## Comment commands

Comment commands run on GitHub and Forgejo. GitLab starts no pipeline for a merge request note, so there [`comments:`](/terragucci/guides/re-plan-from-a-comment/) adds a scheduled job that answers `/terragucci plan` and `/terragucci apply` on its next run. With `apply.when: pull-request` it also answers `/terragucci lock` and `/terragucci unlock`.

| To do this | Atlantis | OpenTaco | terragucci |
|---|---|---|---|
| Plan what the change reaches | `atlantis plan` | `digger plan` | push to the pull request, or comment `/terragucci plan` |
| Plan one project | `atlantis plan -d <dir>` or `-p <project>` | `digger plan -p <project>` | `/terragucci plan <root>`, the root's path from the repo root |
| Plan one workspace | `atlantis plan -w <workspace>` | a project's `workspace` | no flag: each root is a directory with one state |
| Pass flags to the binary | `atlantis plan -- <flags>` | a workflow step | none |
| Apply | `atlantis apply`, before merge | `digger apply`, before merge by default | merge: the default branch's wave jobs apply ([before merge](#apply-before-or-after-merge) is a setting) |
| Apply part of the change | `atlantis apply -d <dir>` or `-p <project>` | `digger apply -p <project>` | `/terragucci apply wave-<n>` applies the approved waves up to wave n; no single-root apply |
| Re-run an approved apply | `atlantis apply` | `digger apply` | `/terragucci apply` on the merged pull request |
| Lock | at plan time | `digger lock`, or at plan time | with [`locks: plan`](/terragucci/reference/config/#plan-locks) (GitHub, Forgejo), from the first plan; otherwise when it applies before merge or on `/terragucci lock`, with `apply.when: pull-request` |
| Unlock | `atlantis unlock` | `digger unlock` | `/terragucci unlock`, with `apply.when: pull-request` or `locks: plan` |
| Import | `atlantis import <address> <id>` | none | refused; [an `import` block](#left-out-on-purpose) in the change |
| Remove from state | `atlantis state rm <address>` | none | refused; [a `removed` block](#left-out-on-purpose) in the change |
| Pass a failed policy | `atlantis approve_policies` | none | refused from a comment; a person `policy.override` lists runs [`terragucci override`](/terragucci/reference/policy/#overriding-a-denial) for one root's plan |
| Approve | the forge's review | the forge's review | [`terragucci approve`](/terragucci/reference/cli/#approve) for a wave its gate holds, or the forge's review under [`approval: pr-review`](/terragucci/guides/approve-a-wave/#approval-modes) |

With [`atlantis_comments: true`](/terragucci/reference/config/#keys), `atlantis plan`, `atlantis plan -d <dir>` and `atlantis apply` work as the `/terragucci` comments. The alias changes only the words. `atlantis apply` on an open pull request is still refused unless `apply.when: pull-request` is set and its requirements pass. `-p`, `-w`, `--` and `atlantis apply -d` are refused with the reason from the tables here.

A comment naming `approve`, `merge`, `destroy`, `import`, `state` or `force-unlock` gets a reply that a comment never runs it. What each command accepts is under [Comment forms](/terragucci/guides/re-plan-from-a-comment/#comment-forms).

## Settings

| Setting | Atlantis | OpenTaco (`digger.yml`) | terragucci (`terragucci.yml`) |
|---|---|---|---|
| Which directories | `projects[].dir`, `autodiscover` | `projects[].dir`, `generate_projects` | detected: every directory with a backend, `cloud` block or provider; `roots` globs to narrow, which an import writes from the projects' directories |
| Project name | `projects[].name` | `projects[].name` | none: a root goes by its path from the repo root |
| Workspace | `projects[].workspace` | `projects[].workspace` | none: each root is a directory with one state |
| What triggers a plan | `autoplan.when_modified`, `autoplan.enabled` | `include_patterns`, `exclude_patterns`, `on_pull_request_pushed` | no key: a root plans when a file in it, a local module it calls or its var files changed, and so does every root that reads its state |
| Binary version | `terraform_version` | a project's `opentofu`, or the action's `terraform-version` or `opentofu-version` input | `binary` and `version`, or the pins the roots carry |
| Order | `execution_order_group`, `depends_on`, `abort_on_execution_order_fail` | `depends_on`, layering | waves from `terraform_remote_state` reads; `waves.after`, which an import writes from `depends_on`, for an order the reads do not give; `waves.canary` puts roots first; Terragrunt's dependency layers |
| Concurrency | `parallel_plan`, `parallel_apply` | | `parallelism` within a job: 1 when either is false, otherwise read from the state backend; `waves.jobs` to spread one wave over several jobs (plain roots on GitHub and Forgejo) |
| Required approval | `apply_requirements: [approved]` | `apply_requirements: [approved]` | branch protection for a merge; with `apply.when: pull-request`, `apply.requires: [approved]`: a reviewer other than the author approved the head |
| Checks green | `apply_requirements: [mergeable]` | `apply_requirements: [mergeable]` | with `apply.when: pull-request`, `apply.requires: [mergeable, checks]`: the forge can merge it, no status failed or running, and `terragucci/plan` passed |
| Up to date | `apply_requirements: [undiverged]` | `apply_requirements: [undiverged]` | with `apply.when: pull-request`, `apply.requires: [undiverged]`: the head contains the default branch |
| Plan requirements | `plan_requirements` | | none: every pull request from the repo itself plans, and a comment plans for someone with write access |
| Apply on merge | | `on_commit_to_default: [digger apply]` | the default, `apply.when: merge` |
| Merge after apply | `automerge` | `auto_merge` | `apply.merge: auto` with `apply.when: pull-request` |
| Lock at plan time | `repo_locks.mode: on_plan` | `pr_locks` | `locks: plan` (GitHub, Forgejo); unset, a root locks when it applies before merge |
| Release locks on close | automatic | `on_pull_request_closed: [digger unlock]`, `on_commit_to_default: [digger unlock]` | automatic: a lock whose pull request merged or closed counts as released |
| Policy | conftest, set in the server's config; a workflow's `policy_check`; a project's `custom_policy_check` | a conftest step you add | `policy`: conftest or OPA over each plan, with Rego in the repo or a shared policy repo at a pinned ref (`policy.source`); the base branch's key decides |
| Custom steps | `workflows` | `workflows` | none: the jobs are generated; `env` sets variables every job gets, which an import writes from the workflows' `env` steps that set a fixed value |
| Cloud credentials | the server's environment | `aws-role-to-assume` in your workflow, or a project's `aws_role_to_assume`, over OIDC | `oidc`: a plan role and an apply role per cloud, from the forge's identity token |
| Many repos | the server's repo config | | a [control repo](/terragucci/concepts/control-repo/)'s `defaults` and `projects` ([Govern many repos](/terragucci/guides/govern-many-repos/)) |
| Terragrunt | a custom workflow, or terragrunt-atlantis-config | `generate_projects` with Terragrunt parsing, or a project's `terragrunt` | detected; `terragrunt` for the version, excludes and roles ([Use Terragrunt](/terragucci/guides/use-terragrunt/)) |
| Drift | drift webhooks | drift detection | `drift`, a cron schedule |

## Apply before or after merge

| | Atlantis | OpenTaco | terragucci |
|---|---|---|---|
| Default | before merge | before merge; `on_commit_to_default` applies after | after merge |
| The other way | | `on_commit_to_default` | `apply.when: pull-request`; on GitLab with `comments:` set |

[Apply a pull request before it merges](/terragucci/guides/apply-before-merge/) sets it up; the open change's settings, gate and signers then come from the default branch.

## Left out on purpose

| Not here | In `atlantis.yaml` or `digger.yml` | terragucci's rule | Do this instead |
|---|---|---|---|
| `import` or `state rm` from a comment | a workflow's `import` or `state_rm`, `import_requirements` | every state change comes from a reviewed commit, through a plan and the gate | an `import` or `removed` block in the change: it plans, shows in the plan note and waits at the gate like any other change |
| Passing a failed policy from a comment | | a policy decides from the base branch; an override names one root's plan and its rules, and only a person the base lists can write one | change the code, change the policy in a reviewed pull request, or [`terragucci override`](/terragucci/reference/policy/#overriding-a-denial) by a listed approver |
| Approving from a comment | | an approval binds the wave's set digest, which a comment does not carry | `terragucci approve` from a checkout, a review under `approval: pr-review`, or a Slack or Teams click through [`terragucci relay`](/terragucci/guides/approve-from-chat/) in your own cloud, which approves the digest the message showed; the approval is signed only under `approval: sealed`, which the relay leaves to the approver's own key |
| Applying one root of a wave | | an approval covers the wave's plans as one set | split the change, or `waves.canary` to send roots out first |
| Flags at run time | a step's `extra_args` | what an approval covers is fixed by the commit and the config | the change itself, or a key in `terragucci.yml` |
| A server or web UI | | the jobs run in your CI and write to your git and your bucket | the plan note, the report artifact, and [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) |

## Next

- [Get your first plan note](/terragucci/getting-started/) to add terragucci next to what you run now.
- [Approve a waiting wave](/terragucci/guides/approve-a-wave/) for the one step that differs most.

---

# Coming from HCP Terraform, Scalr or OTF

Source: https://intentius.io/terragucci/guides/coming-from-hcp-terraform-scalr-or-otf/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/coming-from-hcp-terraform-scalr-or-otf/.
Run `npx terragucci import hcp --organization <org> --dry-run` (`import otf --hostname <host>`, or `import scalr --hostname <account>.scalr.io`) with the token in `TF_TOKEN_<host>`, and show me what it prints. Propose a directory per workspace for each directory it lists as run by several workspaces.
Once I agree, run it without `--dry-run`. Add what the concepts table maps that the import does not write: `policy` with `input: hcp` for an OPA policy set, `steps` for run tasks. Run `npx terragucci config check --json` and `npx terragucci init`, and open a pull request with terragucci.yml, the `terraform.tfvars` files and the generated pipeline.
List the sensitive variables the import named under `pass` that I must recreate as CI secrets, and each Sentinel policy that needs a Rego rewrite.
Do not change a `cloud` or `backend` block, do not run `init -migrate-state`, `state pull` or `state push`, and do not create secrets: a person moves the state.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

Each workspace becomes a root with its own state in your bucket. The jobs `init` writes run in your forge's CI; there is no account and no server, and every record lands in your git and bucket.

## Concepts

| HCP Terraform, Scalr, OTF | terragucci |
|---|---|
| Workspace | a [root](/terragucci/concepts/glossary/#root): one directory, one state. terragucci runs no CLI workspaces |
| Several workspaces on one working directory | a directory per workspace, each with its backend key and `terraform.tfvars`, calling a shared module |
| Workspace state | a key in your S3 bucket, moved by a [backend move](#state-move) |
| Terraform variables | `terraform.tfvars` in the root, committed |
| Environment variables, variable sets | [`env`](/terragucci/reference/config/#keys) for values; CI secrets named under [`pass`](#variables) for the rest |
| Dynamic provider credentials | [`oidc`](/terragucci/reference/environment/#cloud-roles-over-oidc): a plan role and an apply role per cloud |
| Terraform version per workspace | [`version`](/terragucci/reference/config/#a-version-per-root) per root glob, or the root's `.terraform-version` |
| VCS-driven runs, trigger patterns | the [generated pipeline](/terragucci/getting-started/): a pull request plans the roots its files reach |
| Speculative plan | the plan note and `terragucci/plan` status on the pull request |
| Confirm and apply, auto-apply | [`gate`](/terragucci/reference/stages/#gate-policy): `always`, `on-destructive` (default) or `never`, then [approve a wave](/terragucci/guides/approve-a-wave/) |
| Run triggers, `tfe_outputs` | [waves](/terragucci/concepts/waves-and-approvals/#linked-roots): a root that reads another through `terraform_remote_state` applies in a later wave; `waves.after`, which an import writes from run triggers, for an order the reads do not give |
| Sentinel policy set | [`policy`](/terragucci/reference/policy/) in Rego, rewritten by hand |
| OPA policy set | `policy.input: hcp` with `engine: opa`; `policies.hcl` [runs as is](/terragucci/reference/policy/#hcp-terraform-policy-sets) |
| Scalr OPA policy group | `policy` with `engine: opa` and `input: plan`, each policy's `input.tfplan` changed to `input`; a check of `input.tfrun` is rewritten |
| Soft-mandatory override | [`terragucci override`](/terragucci/reference/policy/#overriding-a-denial) by a person `policy.override` lists |
| Run tasks | [`steps`](/terragucci/guides/run-steps/) after `plan`, with `on_failure: fail` or `approve` |
| Workspace lock | [root locks](/terragucci/reference/config/#plan-locks) and the backend's lock file |
| Agents, remote execution | jobs on your CI's runners, your own ones by label with [`runner`](/terragucci/guides/add-to-a-repo/#self-hosted-runners) |
| Health assessments | [`drift`](/terragucci/guides/turn-on-drift-checks/), a cron schedule |
| Cost estimation | [`cost`](/terragucci/guides/estimate-cost/) with Infracost |
| Notifications | [`notify`](/terragucci/guides/notify-a-chat-channel/): Slack, Teams or a signed webhook |
| Private registry | [a module registry](/terragucci/guides/publish-modules/#serve-a-module-registry) in your bucket |
| Ephemeral workspaces | [ephemeral environments](/terragucci/guides/ephemeral-environments/) per pull request, with a TTL |
| Teams and permissions | your forge's permissions and cloud IAM ([access and identity](/terragucci/standards/access-and-identity/)) |
| Run history | the [report](/terragucci/guides/keep-reports-in-a-bucket/) per run and [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) |

## Import the workspaces

`terragucci import` reads the workspaces over the platform's API and writes `terragucci.yml`, with the same token Terraform uses for the host, in `TF_TOKEN_<host>` or `credentials.tfrc.json`:

**HCP Terraform**

```bash
export TF_TOKEN_app_terraform_io=...   # a user or team token that reads the workspaces
npx terragucci import hcp --organization acme --dry-run
```

`--hostname` names a Terraform Enterprise host.

**OTF**

```bash
npx terragucci import otf --hostname otf.example.com --organization acme --dry-run
```

**Scalr**

```bash
export TF_TOKEN_acme_scalr_io=...      # or SCALR_TOKEN
npx terragucci import scalr --hostname acme.scalr.io --dry-run
```

It reads every environment the token sees; `--environment` names one, by name or ID.

A workspace becomes a root when it is connected to this repo (the `origin` remote, or `--repo owner/name`), at its working directory, or when a `cloud` block or `remote` backend in the repo names it. Then, for each root:

| On the platform | What the import writes |
|---|---|
| Working directory | `roots` |
| Several workspaces on one directory | nothing: it lists the directory and its workspaces to split, and leaves it out of `roots` |
| Terraform version | `version`, a map of root to release when they differ; `latest` or a range is left to the root's `required_version` |
| OpenTofu (Scalr) | `binary: tofu` when every workspace runs it |
| Terraform variable, not sensitive | `<root>/terraform.tfvars`, unless the file is already there |
| Environment variable, not sensitive | `env`, unless workspaces set it to different values |
| Sensitive variable | its name under `pass.secrets`: `TF_VAR_<key>` for a Terraform variable; the value is never read |
| Variable set (HCP Terraform, OTF) | as the workspace's own variables, which win over the set's |
| Run trigger (HCP Terraform) | `waves.after`, unless a `terraform_remote_state` read already gives the order |
| Policy group (Scalr) | nothing: it lists each group, its repo and each policy's enforcement level, to port as [below](#policies) |

It prints every setting under the headings of the [other imports](/terragucci/reference/cli/#import): written, done with no key, not mapped. A workspace connected to another repo, or to none that no block in the repo names, is listed and skipped. Scalr's API lists no run triggers, so for Scalr an order the reads do not give goes in `waves.after` by hand.

## Steps

1. Run the [import](#import-the-workspaces). Where it lists several workspaces on one working directory, give each its own directory, with the code in a module that each root calls:

   ```text
   modules/network/        the shared code
   envs/dev/network/       main.tf calls the module; backend.tf; terraform.tfvars
   envs/prod/network/      the same, with prod's key and values
   ```

2. Move each workspace's state into the bucket ([state move](#state-move)), one root at a time, before its backend change merges.

3. Create the secrets the import listed under `pass`, and copy any variable it did not write ([variables](#variables)).

4. Port the policies ([policies](#policies)) and run tasks ([run tasks](#run-tasks)).

5. Write the pipeline and open a pull request:

   ```bash
   npx terragucci config check
   npx terragucci init
   ```

   The plan note on that pull request should show no change for each moved root.

6. Disconnect each moved workspace from its repository and lock it, so nothing runs against the old state.

## State move

A [backend move](/terragucci/guides/move-resources-between-roots/#move-a-state-to-a-new-backend) reads the workspace's current state version over the platform's API and writes it to your bucket, approved by digest like any migration. Change the `cloud` block to the `s3` block and add the migration in one pull request, with the token in `TF_TOKEN_<host>` as a CI secret:

```yaml
# migrations/move-network.yml
backends:
  - root: envs/prod/network
    from:
      backend: cloud
      config:
        hostname: app.terraform.io
        organization: acme
        workspaces:
          name: prod-network
```

[Migration files](/terragucci/reference/migration-files/#workspaces) lists the keys.

### By hand

With Terraform or OpenTofu (`tofu` in place of `terraform`). Neither binary migrates straight out of a `cloud` block, so the block becomes a `remote` backend first.

1. Stop new runs on the workspace: disconnect its repository and cancel queued runs.

2. Replace the root's `cloud` block with a `remote` backend that names the same workspace:

   ```hcl
   terraform {
     backend "remote" {
       hostname     = "app.terraform.io"
       organization = "acme"
       workspaces {
         name = "prod-network"
       }
     }
   }
   ```

   | Platform | `hostname` |
   |---|---|
   | HCP Terraform | `app.terraform.io`, or your Terraform Enterprise host |
   | Scalr | `<account>.scalr.io` |
   | OTF | your OTF host |

   ```bash
   terraform login app.terraform.io
   terraform init -reconfigure
   ```

3. Replace the `remote` backend with the bucket, and migrate:

   ```hcl
   terraform {
     backend "s3" {
       bucket       = "acme-state"
       key          = "envs/prod/network.tfstate"
       region       = "us-east-1"
       use_lockfile = true
     }
   }
   ```

   ```bash
   terraform init -migrate-state
   ```

   Answer `yes` to copy the state.

4. Check the copy:

   ```bash
   terraform plan
   ```

   It should report no changes. Commit the `s3` block; the old state stays on the platform until you delete the workspace.

## Variables

| Variable on the platform | Where it goes |
|---|---|
| Terraform variable, not sensitive | `terraform.tfvars` in the root |
| Environment variable, not sensitive | `env` in `terragucci.yml`, which every job gets |
| Variable set, not sensitive | `env`, or the same values in each root's `terraform.tfvars` |
| Cloud credentials | `oidc` roles; no static keys |
| Sensitive value | see the tabs |

Sensitive values cannot be read back from the platform; copy them from where they came from.

**GitLab**

A masked CI/CD variable named `TF_VAR_<name>` reaches every job, and `TF_` variables pass to the binary as set.

**GitHub and Forgejo**

Create a repository secret named as the variable, such as `TF_VAR_db_password`, and list it under [`pass`](/terragucci/reference/config/#secrets-and-variables); the jobs that plan, apply and check drift get it under that name. A repository variable goes under `vars`.

```yaml
pass:
  secrets: [TF_VAR_db_password]
```

## Policies

**OPA policy set**

Copy the set's Rego and `policies.hcl` into the repo, or point `policy.source` at its repo:

```yaml
policy:
  engine: opa
  path: policies
  input: hcp
```

`input.plan` and `input.run` carry HCP Terraform's field names; [the run fields](/terragucci/reference/policy/#the-run-fields) lists what each holds.

**Sentinel**

terragucci does not run Sentinel. Rewrite each policy in Rego over the plan JSON (`input: plan`), with a `deny` rule per check ([writing a policy](/terragucci/reference/policy/#writing-a-policy)). A soft-mandatory policy becomes a denial that a person in `policy.override` can let through; an advisory one becomes a `warn` rule.

**Scalr**

Scalr hands a policy the plan as `input.tfplan` and the run (workspace, environment, VCS, user, cost estimate) as `input.tfrun`. Set `input: plan` and change `input.tfplan` to `input`; terragucci has no `tfrun`, so rewrite a check of it against [the run fields](/terragucci/reference/policy/#the-run-fields) under `input: hcp`, or drop it. In `scalr-policy.hcl`, a `hard-mandatory` policy becomes a `deny` rule, a `soft-mandatory` one a `deny` rule a person in `policy.override` can let through, and an `advisory` one a `warn` rule. `terragucci import scalr` lists each policy group and its policies' levels.

## Run tasks

A run task posts the plan to a service and waits for a pass or fail. A step runs a command in the job instead, with the plan file in `TG_PLAN_FILE`:

```yaml
steps:
  - name: scan
    run: ./scripts/scan.sh "$TG_PLAN_FILE"
    after: plan
    on_failure: approve
```

| Run task enforcement | Step |
|---|---|
| Mandatory | `on_failure: fail`, the default: the root fails |
| Advisory | `on_failure: approve`: the wave waits at its gate for a person |

## Limits

| On the platform | In terragucci today |
|---|---|
| State move | one workspace per entry of a backend move |
| Workspace settings | [the import](#import-the-workspaces) reads directories, versions, variables and run triggers; agent pools, auto-apply, run tasks and policy sets are listed, not written |
| Sentinel | not run; each policy is rewritten in Rego |
| HCP Terraform Stacks | no equivalent; a Stack's components become roots ordered by `terraform_remote_state` |
| No-code provisioning, workspace UI | none; changes come through pull requests |
| Sensitive variables | not exported by the platform; recreated from their source |
| Roots still on a `cloud` block | planned, but [migrations](/terragucci/guides/move-resources-between-roots/), [export](/terragucci/guides/export-a-state-version/), [state versions](/terragucci/guides/find-a-state-version/) and [ephemeral copies](/terragucci/guides/ephemeral-environments/) refuse them; on remote execution the job's `oidc` roles do not reach the run |
| Run history | stays on the platform |

## Next

- [Add terragucci to a repo](/terragucci/guides/add-to-a-repo/) for the forge settings.
- [Scope state access](/terragucci/guides/scope-state-access/) to give each environment's role only its keys.
- [Coming from Spacelift or env zero](/terragucci/guides/coming-from-spacelift-or-env-zero/) for env zero's remote backend, which moves the same way.

---

# Coming from Spacelift or env zero

Source: https://intentius.io/terragucci/guides/coming-from-spacelift-or-env-zero/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/coming-from-spacelift-or-env-zero/.
Run `npx terragucci import spacelift --dry-run` (or `import env0 --dry-run` for env zero) and report what it would write, each setting it lists as not mapped, and each stack or environment it names as sharing a directory. Propose a directory per stack or environment where one directory serves several.
Run the import without `--dry-run`, then add `policy` for plan policies with `input.terraform` changed to `input`. Run `npx terragucci config check --json` and `npx terragucci init`, and open a pull request with terragucci.yml, the policies and the generated pipeline.
List the secrets I must recreate and add their names under `pass`; list each policy with no counterpart, and each stack or environment whose state the platform manages.
Do not change a `cloud` or `backend` block, do not run `init -migrate-state`, `state pull` or `state push`, and do not create secrets: a person moves the state.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

Each stack or environment becomes a root with its own state in your bucket. The jobs `init` writes run in your forge's CI; there is no account and no server, and every record lands in your git and bucket.

## Import

```bash
npx terragucci import spacelift   # reads .spacelift/config.yml and the spacelift_* resources
npx terragucci import env0        # reads env0-discovery.yml, each env0.yml and the env0_* resources
```

Each command writes `terragucci.yml` from what the repo holds: the runtime config or discovery file, and the admin code that declares the stacks or environments, read from every `.tf` file in the repo. It reads no API, so a stack, context or variable that exists only on the platform is not in it. Each setting is printed under one of the headings of [`terragucci import`](/terragucci/reference/cli/#import), quoting the terragucci cell of its row in the table below. `--dry-run` prints what would be written.

| Read from | Spacelift | env zero |
|---|---|---|
| A root per | `spacelift_stack` resource or `stacks` entry, at its `project_root` | environment, at its `env0_template`'s `path`, else the root its first variable file is in |
| `binary` and `version` | `terraform_workflow_tool`, `terraform_version`, `opentofu_version`; a version per root glob when the stacks differ | the template's `type`, `terraform_version`, `opentofu_version` |
| `steps` | each hook list, for the roots of the stacks that run it, with attached contexts' hooks around the stack's own | `env0.yml`'s `deploy` steps, for the root the file is in |
| `waves.after` | `spacelift_stack_dependency`, unless the roots' `terraform_remote_state` reads already give the order | |
| `env` | `stack_defaults.environment`, and a variable that is not `write_only` on a context every stack gets | a variable that is not sensitive on no environment or template; an `echo NAME=value >> $ENV0_ENV` line |
| `pass.secrets` | each `write_only` variable's name, the provider's default | each sensitive variable's name, `TF_VAR_` first for a Terraform variable |
| `gate: always` | every stack's `autodeploy` off, the provider's default | every environment's `requiresApproval` on, or `approve_plan_automatically` off |
| `drift` | `spacelift_drift_detection`'s schedule | `driftDetectionCron`, `drift_detection_cron` and `env0_environment_drift_detection` |
| `ephemeral` | | the roots of environments with a `ttl`, or in a project whose policy's `default_ttl` gives one, which becomes `ephemeral.ttl` |
| Named, nothing written | managed state, policies, mounted files, workspaces, runner images, worker pools, cloud integrations | the remote backend, workspaces, variable files outside the root, variable sets, credentials, agents |

Neither import moves state; a [state move](#state-move) does, one root at a time.

## Concepts

| Concept | Spacelift | env zero | terragucci |
|---|---|---|---|
| Root | stack | environment | a [root](/terragucci/concepts/glossary/#root): one directory, one state; an import writes `roots` from the stacks' project roots or the environments' template paths |
| Shared code | several stacks on one project root | several environments from one template | a directory per stack or environment, each with its backend key and `terraform.tfvars`, calling a shared module |
| Workspace | `terraform_workspace` | `workspaceName`, `workspace` | none: each root is a directory with one state |
| Managed state | managed state, `manage_state` | env zero's remote backend, `isRemoteBackend` | a key in your S3 bucket, moved by a [backend move](#state-move); an import names each stack or environment whose state moves |
| Own backend | your own backend | your own S3 backend | the same backend; nothing moves |
| Variables | context and stack environment variables | variables | [`env`](/terragucci/reference/config/#keys) for values every root gets; a secret's name under [`pass`](#variables), whose value you create as a CI secret; a root's own values in its `terraform.tfvars` |
| Files | context and stack mounted files | | files committed in the root, such as `terraform.tfvars` |
| Cloud credentials | cloud integration | credentials | [`oidc`](/terragucci/reference/environment/#cloud-roles-over-oidc): a plan role and an apply role per cloud |
| Version | `terraform_version`, `opentofu_version`, `terraform_workflow_tool` | a template's `type`, `terraform_version`, `opentofu_version` | `binary`, and [`version`](/terragucci/reference/config/#a-version-per-root) for every root or per root glob, or the root's `.terraform-version` |
| Hooks | hooks: `before_init`, `after_plan`, `before_apply` and the rest | custom flows (`env0.yml`) | [`steps`](/terragucci/guides/run-steps/) before or after `init`, `plan`, `apply` and `drift`, for the roots the hook ran in; nothing runs at a destroy or a task |
| Runner image | `runner_image` | | `image`: one image for every job, built FROM the terragucci image for the binary |
| Plan policy | plan policy | approval policy (OPA) | [`policy`](/terragucci/reference/policy/) over each plan, with [cost](/terragucci/guides/estimate-cost/#cost-in-the-policy) in `input.cost` |
| Approval | approval policy, `autodeploy` off | approval policy, `requiresApproval` | [`gate`](/terragucci/reference/stages/#gate-policy) and [approval modes](/terragucci/guides/approve-a-wave/#approval-modes); [`cost.approve_above`](/terragucci/guides/estimate-cost/#hold-a-wave-over-an-amount); an import writes `gate: always` when every stack or environment waits for an approval |
| Triggers | push and trigger policies, project globs | triggers, `continuousDeployment`, `pullRequestPlanDeployments` | the [generated pipeline](/terragucci/getting-started/): a pull request plans the roots its files reach; merge applies them |
| Order | stack dependencies, output references | workflows | [waves](/terragucci/concepts/waves-and-approvals/#linked-roots): a root that reads another through `terraform_remote_state` applies in a later wave; an import writes `waves.after` for a stack dependency the reads do not give |
| Access | login policy, spaces | RBAC | your forge's permissions and cloud IAM ([access and identity](/terragucci/standards/access-and-identity/)) |
| Notifications | notification policy | notifications | [`notify`](/terragucci/guides/notify-a-chat-channel/): Slack, Teams or a signed webhook |
| Drift | drift detection | drift detection, `driftDetectionCron` | [`drift`](/terragucci/guides/turn-on-drift-checks/), one cron schedule over every root, and a pull request for drift on a literal; it never reconciles |
| TTL | | environment TTL | [ephemeral environments](/terragucci/guides/ephemeral-environments/) per pull request, with a TTL; an import writes `ephemeral` for the environments that expire |
| Cost | | cost monitoring | [`cost`](/terragucci/guides/estimate-cost/): an estimate per plan, not billed spend |
| Workers | private workers, `worker_pool_id` | self-hosted agents | your CI's runners, your own ones by label with [`runner`](/terragucci/guides/add-to-a-repo/#self-hosted-runners) |
| Module registry | module registry | module registry | [a module registry](/terragucci/guides/publish-modules/#serve-a-module-registry) in your bucket |
| Run history | run history | deployment log | the [report](/terragucci/guides/keep-reports-in-a-bucket/) per run and [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) |

## Steps

1. Give each stack or environment a directory. Where several share one, put the code in a module that each root calls:

   ```text
   modules/network/        the shared code
   envs/dev/network/       main.tf calls the module; backend.tf; terraform.tfvars
   envs/prod/network/      the same, with prod's key and values
   ```

2. Replace each output reference between stacks with a `terraform_remote_state` read of the upstream root's key, so the waves follow it.

3. Move each managed state into the bucket ([state move](#state-move)), one root at a time, before its backend change merges.

4. Run the [import](#import) for the settings it maps, then copy what it names as not mapped: the variables ([variables](#variables)) and the policies ([policies](#policies)).

5. Write the pipeline and open a pull request:

   ```bash
   npx terragucci config check
   npx terragucci init
   ```

   The plan note on that pull request should show no change for each moved root.

6. Disable each moved stack or environment on the platform so nothing runs against the old state.

## State move

A [backend move](/terragucci/guides/move-resources-between-roots/#move-a-state-to-a-new-backend) writes managed state to your bucket, approved by digest like any migration. For env zero it reads the environment's state over the remote backend's API: `backend: remote`, `hostname: backend.api.env0.com`, the organization ID and the workspace. For Spacelift it reads a state file you pulled, with `backend: file`. [Migration files](/terragucci/reference/migration-files/#workspaces) lists the keys. A stack or environment already on your own backend skips this.

By hand, with Terraform or OpenTofu (`tofu` in place of `terraform`):

**Spacelift**

1. Turn on external state access for the stack, and stop its runs.

2. In the root, put a `remote` backend that reads the stack's state, with the account name as the organization and the stack ID as the workspace, and pull the state:

   ```hcl
   terraform {
     backend "remote" {
       hostname     = "spacelift.io"
       organization = "acme"
       workspaces {
         name = "prod-network"
       }
     }
   }
   ```

   ```bash
   terraform init -reconfigure
   terraform state pull > prod-network.tfstate
   ```

   Authenticate as Spacelift's external state access page describes.

3. Replace the `remote` backend with the bucket, and push the file:

   ```hcl
   terraform {
     backend "s3" {
       bucket       = "acme-state"
       key          = "envs/prod/network.tfstate"
       region       = "us-east-1"
       use_lockfile = true
     }
   }
   ```

   ```bash
   terraform init -reconfigure
   terraform state push prod-network.tfstate
   ```

4. Run `terraform plan`; it should report no changes. Delete the pulled file, commit the `s3` block.

**env zero**

1. Stop the environment's deployments.

2. env zero's remote backend speaks the same protocol as HCP Terraform's. Replace the `cloud` block with a `remote` backend naming the same organization ID and workspace, and initialise it. Neither binary migrates straight out of a `cloud` block.

   ```hcl
   terraform {
     backend "remote" {
       hostname     = "backend.api.env0.com"
       organization = "<org-id>"
       workspaces {
         name = "prod-network"
       }
     }
   }
   ```

   ```bash
   terraform login backend.api.env0.com
   terraform init -reconfigure
   ```

3. Swap in the `s3` block from the Spacelift tab and run `terraform init -migrate-state`, answering `yes`.

4. Check that `terraform plan` finds nothing to change, then commit the `s3` block.

## Variables

| Variable on the platform | Where it goes |
|---|---|
| Terraform variable, not sensitive | `terraform.tfvars` in the root |
| Environment variable, not sensitive | `env` in `terragucci.yml`, which every job gets |
| Cloud credentials | `oidc` roles; no static keys |
| Sensitive value | see the tabs |

Secret values cannot be read back from either platform; copy them from where they came from.

**GitLab**

A masked CI/CD variable named `TF_VAR_<name>` reaches every job, and `TF_` variables pass to the binary as set.

**GitHub and Forgejo**

Create a repository secret named as the variable, such as `TF_VAR_db_password`, and list it under [`pass`](/terragucci/reference/config/#secrets-and-variables); the jobs that plan, apply and check drift get it under that name. A repository variable goes under `vars`.

```yaml
pass:
  secrets: [TF_VAR_db_password]
```

## Policies

| Policy | terragucci |
|---|---|
| Spacelift plan policy | `policy` with `input: plan`; change `input.terraform` to `input`. `input.spacelift` (the run, stack and commit) has no counterpart, and `deny` and `warn` rules count as they do there |
| env zero approval policy | `policy` over the plan JSON at `input`, with cost at `input.cost`; a rule that asked for approval becomes `cost.approve_above` or `gate: always` |
| Spacelift approval policy | `gate` decides which waves wait, and an [approval](/terragucci/guides/approve-a-wave/) binds the wave's plans; how many reviewers a change needs is the forge's branch protection |
| Push, trigger policy | none: the pipeline plans what a pull request reaches, applies on merge, and orders waves from `terraform_remote_state` |
| Login policy | none: the forge's sign-in |
| Task policy | none: a state change comes from an `import`, `removed` or `moved` block, or a [migration](/terragucci/guides/move-resources-between-roots/), in a reviewed commit |
| Notification policy | `notify` |

## Limits

| On the platform | In terragucci today |
|---|---|
| State move | a backend move or by hand, as above |
| Stack and environment settings | [`terragucci import`](#import) reads the repo's files and admin code, not the platforms' APIs; what lives only on the platform is copied by hand |
| Tasks (ad hoc commands) | none; state changes come through pull requests |
| Drift reconciliation | the drift job reports and opens a pull request for drift on a literal; it never applies to put the code back |
| Push, trigger, login and task policies | no counterpart; see [policies](#policies) |
| Blueprints, templates in the UI | none; a new root is a directory in a pull request |
| Sensitive variables | not exported by the platform; recreated from their source |
| Run history | stays on the platform |

## Next

- [Add terragucci to a repo](/terragucci/guides/add-to-a-repo/) for the forge settings.
- [Run steps around a stage](/terragucci/guides/run-steps/) for hooks.
- [Coming from HCP Terraform, Scalr or OTF](/terragucci/guides/coming-from-hcp-terraform-scalr-or-otf/) for the workspace platforms.

---

# Ephemeral environments per pull request

Source: https://intentius.io/terragucci/guides/ephemeral-environments/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/ephemeral-environments/.
Look at this repo's roots and tell me which of them could be copied per pull request with ephemeral: name each root's backend and the key its copy would get, and, in a Terragrunt repo, whether the remote_state key reads TERRAGUCCI_EPHEMERAL_SUFFIX.
Do not edit terragucci.yml or run terragucci init.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

With `ephemeral` set, each open pull request gets an environment of its own to try the change in before it merges: the roots you name, applied from its head under state keys nothing else uses.

| When | What terragucci does |
|---|---|
| the pull request opens, or gets a push | plans the environment, waits at the gate as `gate` says, and applies it |
| the pull request closes or merges | plans the environment's destroy and applies it |
| its TTL passes first | the sweep destroys it the same way |

The state key is the root's own with `-pr-<n>` added: `envs/preview/app/terraform.tfstate` becomes `envs/preview/app/terraform-pr-12.tfstate`. Nothing about the root itself changes. Every apply and destroy is on the [audit trail](/terragucci/reference/audit-trail/), and the [estate page](/terragucci/guides/see-every-project/) lists each live environment with its expiry.

## Turn it on

1. Pick the roots. A root whose resources have fixed names collides with itself once a second state applies it, so let each environment name its resources apart, with a `random_id` suffix for example.

2. Add the key to `terragucci.yml` on the default branch:

   ```yaml
   ephemeral:
     roots: ["envs/preview/*"]
     ttl: 24h      # default; m, h or d
     sweep: 30     # minutes between the sweep's runs, 5 to 60
   ```

3. Run `npx terragucci init` and commit what it writes: the `ephemeral` job, and on GitHub and Forgejo the sweep workflow `terragucci-ephemeral.yml`.

4. Open a pull request. The `ephemeral` job runs from the default branch's workflow. It checks out the pull request's head apart and applies the environment there:

   ```text
   terragucci ephemeral: pull request 12: its copy of envs/preview/app under the state keys suffixed -pr-12, from 3f9c21aa
   terragucci ephemeral: envs/preview/app: 4 to change at s3://acme-state/envs/preview/app/terraform-pr-12.tfstate
   terragucci ephemeral: applied envs/preview/app at s3://acme-state/envs/preview/app/terraform-pr-12.tfstate
   terragucci ephemeral: pull request 12: its copy applied; it expires 2026-10-10T16:02:11.000Z, and closing the pull request destroys it before then
   ```

5. Close or merge it. The destroy plans and applies, and `_gates/tf-ephemeral/done.jsonl` on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) records it with the reason `closed`.

## The gate

The environment waits at gate `pr-<n>` of op `tf-ephemeral` under the `gate` your waves use:

| `gate` | Waits on |
|---|---|
| `always` | any change |
| `on-destructive` | a change that destroys or replaces something |

The job prints the command that approves it:

```bash
terragucci approve ephemeral 12 --plan jcs1-sha256:6d2b...
```

The next push or a re-run of the job then applies it. Under `approval: sealed` only a sealed approval counts.

No gate holds a destroy. Closing the pull request is the decision, and so is the TTL the default branch set. The destroy still plans first, and its record carries that plan's digest.

## The TTL

An environment expires `ttl` after the last apply that changed it, so a pull request that keeps getting pushes keeps it. Every `sweep` minutes, a run on the default branch destroys each environment whose TTL passed, and each one whose pull request the forge reports closed. A failed destroy leaves the environment live and flagged on the estate page; the next sweep tries again.

## Per forge

| Forge | It applies | It is destroyed on close |
|---|---|---|
| GitHub | in the `ephemeral` job, on `pull_request_target` from the default branch | by the same job, on the `closed` event |
| Forgejo | the same | the same |
| GitLab | in the `ephemeral` job of the merge request's pipeline, with terragucci.yml read from the default branch | by the sweep: GitLab starts no pipeline when a merge request closes. Add a pipeline schedule with `TERRAGUCCI_SCHEDULE=ephemeral` |

Forks never get one. On GitLab the job needs the project token, so `ephemeral` with `gitlab.token: protected` is a config error.

## Supported roots

| Setup | Gets an environment |
|---|---|
| OpenTofu, Terraform or [choudoufu](/terragucci/concepts/glossary/#choudoufu), with an `s3`, `azurerm`, `gcs` or `local` backend, or on GitLab-managed state | yes |
| a Terragrunt unit whose `remote_state` key reads `TERRAGUCCI_EPHEMERAL_SUFFIX` | yes; see [Terragrunt units](#terragrunt-units) |
| a CDK Terrain stack, with `synth` | yes; see [Synthesized roots](#synthesized-roots) |
| a root in HCP Terraform (a `cloud` block), or on another backend | no: the job fails with a config error naming the root |
| a Terragrunt unit whose key does not read the suffix | no: the job fails with a config error naming the file, before anything plans |

terragucci never selects a CLI workspace. The suffix goes in the backend block's own key attribute (`prefix` on `gcs`), so the environment's lock file and a bucket listing show it plainly.

On GitLab-managed state the suffix goes on the state name in `address`, `lock_address` and `unlock_address`, from the block or the `TF_HTTP_*` variables: `.../terraform/state/app` becomes `.../terraform/state/app-pr-12`, which GitLab creates on its first write. A lock address that is not `<address>/lock` is refused, so a copy never takes the root's own lock. An `http` backend that is not GitLab's is refused.

## Terragrunt units

A unit's state key comes from its `remote_state` block, which terragucci leaves as you wrote it. Make the key read the suffix from `TERRAGUCCI_EPHEMERAL_SUFFIX`, which is empty in every other job:

```hcl
remote_state {
  backend = "s3"
  config = {
    bucket = "acme-state"
    key    = "${path_relative_to_include()}/terraform${get_env("TERRAGUCCI_EPHEMERAL_SUFFIX", "")}.tfstate"
  }
}
```

The `ephemeral` job sets it to `-pr-<n>` and prepares each unit with `terragrunt run -- init`, so `live/preview/app/terraform.tfstate` becomes `live/preview/app/terraform-pr-12.tfstate`. A `dependency` block reads its upstream's environment too, since the upstream's key takes the same suffix. The units apply in the order their dependencies give, and are destroyed in reverse.

Before anything plans, the job reads the backend Terragrunt initialised each unit with. A key without the suffix stops the job with a config error, so no environment ever runs against a unit's own state:

```text
terragucci: live/preview/app: its s3 backend's key is live/preview/app/terraform.tfstate with TERRAGUCCI_EPHEMERAL_SUFFIX set, which is the unit's own state, so its copy is refused; make the remote_state block's key read the suffix, ...
```

The `terragucci.hcl` that [`generate`](/terragucci/guides/generate-root-files/#in-a-terragrunt-repo) writes already reads the suffix in every unit's key.

## Synthesized roots

With `synth`, git holds no roots to copy. The `ephemeral` job runs the synth command in the pull request's checkout first, as every other job does, then copies the stacks `roots` names, such as `cdktf.out/stacks/preview`. The destroy runs it again on the commit the environment was applied from. A stack's copy takes the suffix on the key its backend construct gives, so give the stack a backend that keeps its state outside the job (`S3Backend`, for one). CDK Terrain's default local state lives in the job's checkout and is gone when the job ends.

A synth command that fails stops the job, and nothing applies.

## Pull request code

Unmerged pull request code runs with the apply role in this job, its synth command included, as it does under [apply before merge](/terragucci/guides/apply-before-merge/). Scope that role to the `-pr-` keys with [a role per environment](/terragucci/guides/scope-state-access/), and require reviews in branch protection.

Every flag is on [CLI commands](/terragucci/reference/cli/#ephemeral), and every key on [terragucci.yml keys](/terragucci/reference/config/#ephemeral-environments).

---

# Estimate the cost of a change

Source: https://intentius.io/terragucci/guides/estimate-cost/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/estimate-cost/.
Add `cost: true` to terragucci.yml, run `npx terragucci config check` and `npx terragucci init`, and open a pull request.
Tell me which secret I must create and which job gets it. Do not create the secret or an Infracost account.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

A cost table in each pull request's plan note, with a row per root the change reaches (a unit, in a Terragrunt repo) and a total row. Infracost runs in your plan job on your key; terragucci holds no account and sends nothing anywhere else.

```text
Monthly cost: +20.00 USD over 1 of 1 root, from infracost.

| Root     | Before | After | Change |
|----------|--------|-------|--------|
| envs/app | 0.00   | 20.00 | +20.00 |
| Total    | 0.00   | 20.00 | +20.00 |
```

## Prerequisites

| You need | Why |
|---|---|
| The [pipeline](/terragucci/getting-started/) | `init` adds the key and the install step to the plan jobs |
| An Infracost API key | Infracost prices each resource through its pricing API, on your key |

## Steps

1. Store the key as a secret named `INFRACOST_API_KEY`.

**GitHub**
       A repository secret under Settings, Secrets and variables, Actions.
**GitLab**
       A masked CI/CD variable, left unprotected, since the plan job runs in merge request pipelines.
**Forgejo**
       The same as GitHub; Forgejo keeps them under Settings, Actions, Secrets.

   The plan job runs the pull request's code, which can read the key, so give Infracost a key that can only price.

2. Turn it on in `terragucci.yml`:

   ```yaml
   cost: true
   ```

   With the key under another name:

   ```yaml
   cost:
     key_secret: COST_KEY
   ```

3. Write the pipeline again and merge it.

   ```bash
   npx terragucci init
   ```

   | Job | Gets |
   |---|---|
   | plan, and a `/terragucci plan` re-plan | `INFRACOST_API_KEY` from the secret, and an install step that fetches Infracost 0.10.45 and checks it against the release's checksum |
   | each apply wave, `/terragucci apply`, and the resume job | the same: a wave prices its own plans for the policy and `approve_above` |
   | confirm (`apply.when: pull-request`) | nothing: it runs `tf-plan --no-cost` |
   | drift, check | nothing |

4. Open a pull request. After each root plans, the job runs Infracost over its stored plan:

   ```text
   cost: envs/app: +20.00 USD a month
   cost: +20.00 USD a month over 1 of 1 roots
   ```

## Report contents

| Where | What |
|---|---|
| the plan note | the line and the table above; a root Infracost could not price says why |
| `report.json`, `cost` | the estimator, the currency, the change and the totals, and each root's figures; see [Report JSON schema](/terragucci/reference/report-schema/) |
| `roots/<root>/cost.json` | Infracost's own output for the root, beside its `plan.json` |

An estimate that fails never fails the plan. A wave's report keeps its own estimate, and the wave's change sits under `waves[].cost`.

In a Terragrunt repo the estimator reads the plan the wave's `run --all` saved for each unit, and treats each unit as a root.

## Hold a wave over an amount

`approve_above` makes a wave wait for an approval when its monthly change is over the amount, in the estimator's currency, whatever `gate` says:

```yaml
gate: never
cost:
  key_secret: COST_KEY
  approve_above: 100
```

| Case | The wave |
|---|---|
| the change over its roots is more than the amount | waits for an approval of its digest, as under `gate: always`, and its log names the change, the amount and the commit it was read at |
| the change is the amount or less, or the wave lowers the cost | applies under the gate it has |
| a root of the wave could not be estimated | waits, naming the root |
| the wave changes nothing | applies nothing, so it waits for nothing |

The amount is read from the config at base: the commit before the one applied, or the pull request's base with `apply.when: pull-request`. A change that raises or drops the amount waits under the old one, and its log says which amount counts.

The amount, the currency and the wave's change join the wave's set digest. A wave priced differently after its approval applies nothing, exits 4 and names `(monthly cost)` as what moved, as it names a root whose plan moved. [Approve a wave](/terragucci/guides/approve-a-wave/) has the commands.

The plan note sets each wave's change against the amount at base:

```text
Against `cost.approve_above` at base, 100.00 USD a month: wave 1 +20.00 USD, within it; wave 2 +140.00 USD, over it: it waits for an approval whatever the gate.
```

A wave the amount holds says "waits for an approval" in the note's wave table, with the command that approves its digest.

## Cost in the policy

With `cost` set, `tf-plan` and each `tf-apply` wave give the policy the figures as `input.cost`. [Policy](/terragucci/reference/policy/#cost) lists the fields; this one denies a root that adds more than 50 a month:

```rego
package main

deny contains msg if {
  input.cost.root.monthly_delta > 50
  msg := sprintf("this root adds %v %s a month; the most is 50", [input.cost.root.monthly_delta, input.cost.currency])
}
```

## Another estimator

`command` runs any program that prints Infracost's JSON (`totalMonthlyCost`, `pastTotalMonthlyCost`, `diffTotalMonthlyCost` and `currency`). The plan jobs then install nothing.

```yaml
cost:
  key_secret: COST_KEY
  command: node scripts/cost.mjs
```

| The command gets | Value |
|---|---|
| `TG_PLAN_JSON` | the path of the root's plan, `show -json` with sensitive values redacted |
| `TG_ROOT` | the root's path |
| `INFRACOST_API_KEY` | the key from `key_secret` |
| its working directory | the repo's root |

It gets the job's environment less its forge tokens, as the binary does. Each root's estimate may take two minutes.

## Next

- [The plan report](/terragucci/reference/report/)
- [terragucci.yml keys](/terragucci/reference/config/)

---

# Export a state version

Source: https://intentius.io/terragucci/guides/export-a-state-version/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/export-a-state-version/.
Tell me which roots of this repo `terragucci state export` can export, and what each needs (an s3, gcs or azurerm backend that keeps versions), from the roots' backend blocks.
Read only: do not run `terragucci state export`, and do not read or download any state.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

One version of a root's state in a file on your machine that only you can read. A record on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) names who exported which root and version, and who approved it. The [audit trail](/terragucci/reference/audit-trail/) lists it as a `state-export` entry.

The state goes only to the person who runs the command; no job writes it to the reports bucket or as an artifact. Anyone with read access to the repo can read a job's artifact while the forge keeps it (on a public repo, everyone), and a state holds every secret its resources hold. On your machine, the state reaches only someone whose own cloud identity can already read the bucket; terragucci adds another person's approval and the record.

## Prerequisites

| You need | Why |
|---|---|
| A root whose backend keeps versions: `s3` or `gcs` with versioning on, `azurerm` with blob versioning or `snapshot = true`, or [GitLab-managed state](#gitlab-managed-state) | the export reads a version by its id; [Find the state version an apply left](/terragucci/guides/find-a-state-version/) turns versioning on and lists the ids |
| Your own cloud identity that can read the state object | the command runs on your machine with your credentials |
| A checkout whose `origin` you can push to | the request and the record go to `chant/lifecycle` |
| Someone else to approve | an approval by the person who asked does not count |

A Terragrunt unit exports the same way: name the unit, such as `terragucci state export live/app`. Terragrunt prepares it as a [migration](/terragucci/guides/move-resources-between-roots/) does (`init` in the unit through its `remote_state` block), so the export reads the state Terragrunt reads and needs Terragrunt on the path. The command refuses roots with a `cloud` block. A `local` backend, or a store that keeps no versions, has no version id to export. Without `--version`, an `azurerm` backend that keeps snapshots and no blob versions gets a snapshot of the blob, whose time is the id.

## Steps

1. Ask for the version. Take its id from the estate page's State versions section, or leave `--version` out for the current one:

   ```bash
   terragucci state export envs/dev/app --version 3HL4kqtJlcpXroDTDmJ.rmSpXd3dIbrHY
   ```

   It reads the version's metadata and never its body. Then it records the request and exits 3:

   ```text
   state export: alice asks for envs/dev/app's state, s3://acme-state/dev/app.tfstate version 3HL4kqtJlcpXroDTDmJ.rmSpXd3dIbrHY; request sha256:5e0b...
   someone other than you approves it with:
     terragucci approve export envs/dev/app --plan sha256:5e0b...
   then run this command again to download it.
   ```

   The request names you by git's `user.name`, or by `--actor`.

2. Someone else approves the request with the command it printed. Under `approval: sealed` the approval needs a seal (`--sign`) from a key the signers file lists.

3. Run the same command again. It downloads the version and records the export in `_gates/tf-state-export/done.jsonl`. Only then does it write the file:

   ```text
   state export: wrote /tmp/terragucci-export-Xb3k/envs_dev_app.3HL4kqtJlcpXroDTDmJ.rmSpXd3dIbrHY.tfstate: envs/dev/app's state, s3://acme-state/dev/app.tfstate version 3HL4kqtJlcpXroDTDmJ.rmSpXd3dIbrHY, approved by bob
   ```

   The file is mode 0600 in a new directory of its own. `--out <file>` names another place outside the repo; a path inside the repo is refused, so the state is never committed by accident. When the record cannot be pushed, nothing is written.

4. Delete the file when you are done.

A request exports once; running the command again records a new request for a new approval.

## GitLab-managed state

The version id is GitLab's serial, and `--version` takes it: `terragucci state export envs/dev/app --version 7`. Without `--version`, the export takes the current serial. The command calls GitLab with the backend's credentials: set `TF_HTTP_USERNAME` to your GitLab username and `TF_HTTP_PASSWORD` to a personal access token with the `api` scope and the Developer role or higher on the project.

The request checks the version with a `HEAD` and never reads it. Without `--version`, it reads the current state for its serial, since GitLab answers the serial no other way, and keeps nothing else.

## In the audit trail

`terragucci audit` turns the request into an `approval-requested` entry and the approval into an `approval` entry. The export is a `state-export` entry: `who` is the person who exported and `what` the root. Its `detail` holds the location and the version id, who approved it, and the digest of the file, never its contents.

## Next

- [Threat model](/terragucci/reference/threat-model/#exporting-a-state) for what the approval stops and what it does not.
- [`state export`](/terragucci/reference/cli/#state-export) for every flag.

---

# Find the state version an apply left

Source: https://intentius.io/terragucci/guides/find-a-state-version/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/find-a-state-version/.
Find the buckets and containers this repo's roots keep their state in, check whether each keeps versions, and write the commands that would turn it on as a file for me to review. Open a pull request.
Do not change a bucket, a state file or a lock.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

After each `tf-apply` wave, the version id of each root's state, next to the run that wrote it. When a state goes wrong you know which version to restore, and which commit and wave wrote the one after it.

| Where | What it holds |
|---|---|
| the wave's log | one line per root: where its state is and its version id |
| the wave's `report.json` | `roots[].state`, for each root that applied or had nothing to apply |
| the project's `states.json` in the reports bucket | each root's newest 20 versions, each with its commit, wave and report |
| the estate page | a State versions section, per project and root, newest first |
| the [audit trail](/terragucci/reference/audit-trail/) | `detail.state_versions` on the wave's `apply` entry |

terragucci reads only the state object's metadata; it never copies or stores a state's contents. GitLab answers a state's serial only with the state itself, so on [GitLab-managed state](#gitlab-managed-state) terragucci reads the state and keeps only the serial.

## Prerequisites

| You need | Why |
|---|---|
| Roots with an `s3`, `gcs` or `azurerm` backend that keeps versions, or on GitLab-managed state | the version id is the store's own (see below), or GitLab's serial |
| [Reports in a bucket](/terragucci/guides/keep-reports-in-a-bucket/) | `states.json` and the estate page live there |
| The [estate page](/terragucci/guides/see-every-project/), to see the list | the page reads `states.json` |

A Terragrunt unit is listed as a root is. Its working directory is in Terragrunt's cache, so terragucci reads its backend from its evaluated `remote_state` block (`terragrunt render --json`).

Each backend names a version its own way:

| Backend | Version id | Kept when |
|---|---|---|
| `s3` | `x-amz-version-id` | bucket versioning is on |
| `gcs` | the object's generation | object versioning is on |
| `azurerm` | `x-ms-version-id` | blob versioning is on |
| `azurerm` without blob versioning | the time of a snapshot terragucci takes of the state blob after the apply | the backend sets `snapshot = true` |

Other roots are listed with what terragucci knows:

| Root | Listed as |
|---|---|
| a bucket or account that keeps no versions | versions are off: the store keeps only the latest state |
| a `local`, `pg`, `kubernetes` or `consul` backend, or an `http` backend other than GitLab's | versions are off: each write replaces the state |
| a backend that keeps versions terragucci does not read (`remote`) | versions not read, naming why |
| a Terragrunt unit with no `remote_state` block that runs from Terragrunt's cache | versions not read, naming why |

In `report.json` and `states.json`, `versioning` is `off` for the first two rows and `unknown` for the last two.

## Steps

1. Turn on versioning where your state is:

   ```bash
   aws s3api put-bucket-versioning --bucket acme-state --versioning-configuration Status=Enabled
   gcloud storage buckets update gs://acme-state --versioning
   az storage account blob-service-properties update --account-name acmestate --enable-versioning true
   ```

   The store then keeps each version of every state object until a lifecycle rule expires it. A rule that expires noncurrent versions after 90 days keeps the list short and the bill small.

2. Check the apply job can read the state object's metadata, which the apply identity already can for the backend. terragucci uses the credentials the backend's configuration names (`access_key` and `secret_key` for S3; `access_token`, `credentials` or `impersonate_service_account` for GCS; `access_key` or `sas_token` for Azure), else the job's own. A role an S3 backend assumes itself (`assume_role`) is not assumed; if the job's own identity may not read the object, the root is listed with versions unknown and the reason. Reading whether a GCS bucket keeps versions needs `storage.buckets.get`; without it the generation is recorded as kept.

3. Let a wave apply. Each root that applied, or had nothing to apply, gets a line in the log:

   ```text
   envs/dev/platform: state s3://acme-state/envs/dev/platform.tfstate version 3HL4kqtJlcpXroDTDmJ.rmSpXd3dIbrHY
   ```

   A store that keeps no versions prints `versions off` and why. A version that cannot be read never fails the wave.

4. Open the estate page. Run `terragucci estate` (or let its scheduled job run) and open the link it prints. The State versions section lists each root's versions, newest first, each linked to the report of the wave that wrote it; a root whose bucket keeps no versions says versions are off.

## GitLab-managed state

A root on GitLab-managed state is an `http` backend whose `address` is a project's state API, `<api>/projects/<id>/terraform/state/<name>`, in the block or `TF_HTTP_ADDRESS`. The apply job reads the state with the backend's own credentials, `TF_HTTP_USERNAME` and `TF_HTTP_PASSWORD` ([GitLab-managed state](/terragucci/reference/pipeline/#gitlab-managed-state)), and logs its serial:

```text
envs/dev/platform: state https://gitlab.example.com/api/v4/projects/42/terraform/state/dev-platform version 7
```

GitLab keeps each version by serial, so no setting turns versions on.

## Go back to a version

Restoring a state version is a state write outside the gate, so take it through review like any other change. With the version id from the page:

```bash
aws s3api get-object --bucket acme-state --key envs/dev/platform.tfstate \
  --version-id 3HL4kqtJlcpXroDTDmJ.rmSpXd3dIbrHY restore.tfstate
tofu -chdir=envs/dev/platform state push -force restore.tfstate
tofu -chdir=envs/dev/platform plan
```

On GCS the version is a generation, and on Azure a version id or a snapshot. Fetch it, then push it as above:

```bash
gcloud storage cp "gs://acme-state/envs/dev/platform/default.tfstate#1791612469077717" restore.tfstate
az storage blob download --account-name acmestate --container-name tfstate --name platform.tfstate \
  --snapshot 2026-10-10T06:09:35.6000000Z --file restore.tfstate
```

On GitLab-managed state, download the version by its serial with a token that can read the project's state:

```bash
curl --fail --user "$TF_HTTP_USERNAME:$TF_HTTP_PASSWORD" -o restore.tfstate \
  https://gitlab.example.com/api/v4/projects/42/terraform/state/dev-platform/versions/7
```

`state push` takes the backend's lock while it writes. The older state lacks resources created after it, so the plan shows them as creates. Applying it would make a second copy of each. Import them, or remove them from the cloud, before the next wave applies the root.

## Next

- [Report JSON schema](/terragucci/reference/report-schema/) describes `roots[].state` and `states.json`.
- [The reports bucket](/terragucci/reference/reports-bucket/) lists where `states.json` lives and who can read it.

---

# Generate backend and provider files

Source: https://intentius.io/terragucci/guides/generate-root-files/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/generate-root-files/.
Read the backend, provider and required_version blocks in my Terraform directories and propose a generate key for terragucci.yml that writes the same values: shared values at the top, per-directory values under dirs, single-directory values under roots.
Add it, delete the blocks it replaces, run `npx terragucci generate`, `npx terragucci generate --check` and `npx terragucci init`, and open a pull request.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

`terragucci generate` writes three files from `terragucci.yml`.

| File | Holds |
|---|---|
| `backend.tf` | `terraform { backend "<type>" { ... } }` |
| `providers.tf` | a `provider` block per configuration that sets an argument, aliases included |
| `versions.tf` | `required_version`, and `required_providers` from each provider's `source` and `version` |

Each is plain HCL in `fmt`'s layout, and its first line says terragucci wrote it. Only the binary reads them; a directory stays ordinary Terraform or OpenTofu that works by hand or without `generate`.

The check job's `tf-check` fails, naming the file, when a generated file:

| Case | Example |
|---|---|
| differs | someone edited it by hand, or changed the config without running `generate` |
| is missing | a new directory matched, and nobody ran `generate` |
| is left over | the config no longer asks for it |

## Prerequisites

| You need | Why |
|---|---|
| The [pipeline](/terragucci/getting-started/) | `init` adds `terragucci generate --check` to the check job |
| In a Terragrunt repo, an `include "terragucci"` in each unit | the settings reach a unit through `terragucci.hcl` ([In a Terragrunt repo](#in-a-terragrunt-repo)) |

## Steps

1. Put the shared values at the top of `generate`, and what differs under `dirs` and `roots`:

   ```yaml
   roots: ["envs/*/*"]
   generate:
     backend:
       s3:
         bucket: acme-state
         key: "{root}/terraform.tfstate"
         region: us-east-1
         use_lockfile: true
     providers:
       aws:
         source: hashicorp/aws
         version: "6.67.0"
         region: us-east-1
         default_tags:
           tags: { team: platform }
       aws.dr:
         region: us-west-2
     required_version: ">= 1.6"
     dirs:
       "envs/prod/*":
         backend: { s3: { bucket: acme-prod-state } }
     roots:
       envs/prod/network:
         providers: { aws: { region: eu-west-1 } }
   ```

   `{root}` in a value is the directory's path, so each one keeps its own state.

2. Delete what the generated files now hold from your own `.tf` files. `generate` stops while a hand-written file still declares a backend or `required_version`. It never overwrites a `backend.tf`, `providers.tf` or `versions.tf` it did not write.

3. Write the files and check them:

   ```bash
   npx terragucci generate
   npx terragucci generate --check
   ```

   `--dry-run` prints what `generate` would write and writes nothing.

4. Run `npx terragucci init` to add the check, and commit everything.

## Level precedence

| Order | Level | Applies to |
|---|---|---|
| 1 | the top of `generate` | everything |
| 2 | each glob under `generate.dirs` the path matches, in file order | the matching directories |
| 3 | `generate.roots`, keyed by exact path | that directory |

A higher level overrides only the keys it names. Backend arguments and provider settings merge key by key down through nested maps. Naming another backend type replaces the backend. Setting a key to `null` drops what an earlier level set (`backend: null`, `providers: { aws.dr: null }`, `required_version: null`, `disable_init: null`).

In a [control repo](/terragucci/concepts/control-repo/), `defaults.generate` comes first, then the project's own `generate`.

## Providers

Each provider is keyed by its local name: `aws`, or `aws.<alias>` for an aliased configuration. Its `source` and `version` go into `required_providers` and the rest become arguments of the `provider` block; a provider with only those two gets none.

| A map | Is written as | Example |
|---|---|---|
| directly under a provider | a nested block | `default_tags`, azurerm's `features: {}` |
| one level further down | a map value | `tags` |
| anywhere under the backend | a map value | `assume_role: { role_arn: ... }` becomes `assume_role = { role_arn = "..." }` |

Values are literals. A `${` in a value is written as `$${`, so nothing interpolates.

## The version each directory declares

With no `required_version` at any level, `versions.tf` takes the release `version` in `terragucci.yml` gives that path: the first matching glob of [the version map](/terragucci/reference/config/#a-version-per-root), or the one release. A job's version and the code's declared one then come from one key.

An exact `required_version` that disagrees with the pin stops `generate`; a range such as `">= 1.6"` is kept as written, and `required_version: null` writes none. Under `binary: choudoufu`, `version` names a [choudoufu](/terragucci/concepts/glossary/#choudoufu) release, which is not a `required_version`.

## Target directories

The targets are the directories `init` plans (from `roots` or detection) plus each path under `generate.roots`, so naming a new directory there gives it a backend before it has its own. A generated file the config stops asking for is deleted by `generate` and refused by `generate --check`.

## In a Terragrunt repo

For Terragrunt, `generate` writes a single `terragucci.hcl` at the repo's root rather than files in each unit. It holds each unit's settings (resolved through the same three levels, with `{root}` as the unit's path) and the Terragrunt blocks that use them:

| Block | Writes, in each unit's working directory |
|---|---|
| `remote_state`, with `disable_init` | `backend.tf`, from the unit's backend; by default Terragrunt creates no bucket, as for a plain root ([Bucket bootstrap](#bucket-bootstrap)) |
| `generate "terragucci_providers"` | `providers.tf` |
| `generate "terragucci_versions"` | `versions.tf` |

Each unit takes them by including the file, in its `terragrunt.hcl`:

```hcl
include "terragucci" {
  path = find_in_parent_folders("terragucci.hcl")
}
```

`tf-check` checks `terragucci.hcl` (kept in `terragrunt hcl fmt`'s layout) like the other files and also fails when:

| Case | Why |
|---|---|
| a unit does not include `terragucci.hcl` | the settings would never reach it |
| another `.hcl` file declares `remote_state` | two backends would contend in each unit that includes both |
| another `.hcl` file has a `generate` block for `backend.tf`, `providers.tf` or `versions.tf` | two blocks would write one file |

Each unit's key reads `get_env("TERRAGUCCI_EPHEMERAL_SUFFIX", "")` before a closing `.tfstate`, or at its end. The variable is empty in every job but an [ephemeral environment's](/terragucci/guides/ephemeral-environments/#terragrunt-units), so the key is the one `terragucci.yml` gives, and every unit can be copied per pull request.

`generate` gives every unit a backend, or none; a backend for only some units stops it. A unit is a directory holding a `terragrunt.hcl`, less `terragrunt.exclude`; an explicit stack's units are the paths its `unit` blocks generate. Each unit template in the repo must include `terragucci.hcl`. A nested `stack` block stops `generate`, since only Terragrunt can list its units.

The `generate` and `remote_state` blocks in `root.hcl` already keep one repo's units alike. terragucci adds `required_version` from `version` and a check job that refuses a hand edit. In a control repo it also gives plain roots and units across projects one source, `defaults.generate`.

### Bucket bootstrap

`disable_init: false` lets Terragrunt create the state bucket on the first apply, and keep its settings in line after that. Set it at any level, like the backend:

```yaml
generate:
  disable_init: false
  backend:
    s3:
      bucket: acme-state
      key: "{root}/terraform.tfstate"
      region: us-east-1
```

`terragucci.hcl` then writes `disable_init = false` in its `remote_state`. A unit's own value goes into its entry when units differ.

| Job | Backend |
|---|---|
| apply | runs with `TG_BACKEND_BOOTSTRAP`: Terragrunt creates a missing bucket, and turns on versioning, encryption and access blocking on an existing one |
| plan, drift | used as it is; a pull request's code and the plan role never change the bucket |

A pull request that plans a unit before its bucket exists fails. The first apply creates the bucket, so the apply role needs the rights to create and configure buckets. No job touches the bucket while `disable_init` is unset or `true`. A unit set to `false` needs a backend. The key is for Terragrunt units only; `generate` refuses it on a plain root, whose backend is the binary's.

## With synth

`generate` beside [`synth`](/terragucci/guides/plan-cdk-terrain-stacks/) is a config error. The roots are synth's output, so a file written into one is gone at the next synth; the app sets these values through its constructs instead:

| `generate` writes | Set it in the CDK Terrain app with |
|---|---|
| the backend | a backend construct: `S3Backend`, `GcsBackend`, `AzurermBackend`, `LocalBackend`, `HttpBackend`, `PgBackend`, `ConsulBackend`, `CosBackend`, `OssBackend`, `SwiftBackend`, or `CloudBackend` and `RemoteBackend` for HCP Terraform |
| the providers | each provider's construct |
| `required_version` | the stack's `addOverride("terraform.required_version", ...)` |

`config check`, `init` and `terragucci generate` each refuse it and name these constructs.

## In a control repo

`reconcile` runs `generate` in each project before it writes the pipeline, so the generated files land in the same pull request. It also writes the `generate` key into the project's own `terragucci.yml`, where the project's check job reads it. The project file carries no `version`, so a control repo `version` becomes the key's `required_version`. See [Govern many repos](/terragucci/guides/govern-many-repos/).

## Next

- [terragucci.yml keys](/terragucci/reference/config/)
- [The check stage](/terragucci/reference/stages/#check)
- [Choose your binary](/terragucci/guides/use-a-binary/)

---

# Keep secrets out of plan notes and logs

Source: https://intentius.io/terragucci/guides/keep-secrets-out-of-notes/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/keep-secrets-out-of-notes/.
List each variable in this repo's roots that holds a secret and is not marked `sensitive = true`, and each secret a root reads that terragucci.yml does not name under `pass.secrets`.
Add the missing names and `sensitive = true`, run `npx terragucci config check --json` and `npx terragucci init`, and open a pull request. Print names only; never write a secret's value anywhere.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

A secret the plan and apply jobs read by name, whose value never appears in anything terragucci writes or logs.

## Steps

1. Put the value in your forge's secret store, named as the root reads it, such as `TF_VAR_db_password` (on GitLab, a masked CI/CD variable).

2. Mark the variable sensitive in the root:

   ```hcl
   variable "db_password" {
     type      = string
     sensitive = true
   }
   ```

3. Name the secret in `terragucci.yml`. The pipeline holds the name, never the value:

   ```yaml
   pass:
     secrets: [TF_VAR_db_password]
   ```

   `config check` refuses a value written in place of a name. On GitLab every job reads the CI/CD variables already, so the key changes nothing there.

4. Check the file and write the pipeline again:

   ```bash
   npx terragucci config check
   npx terragucci init
   ```

   Each job that plans or applies gets the secret as an environment variable of that name; [Secrets and variables you pass](/terragucci/reference/environment/#secrets-and-variables-you-pass) lists the jobs that get none.

5. Open a pull request. When the plan held a sensitive value, the note says so:

   ```text
   Sensitive values are redacted in the stored plans (2).
   ```

## Redaction

The binary's `show -json` prints sensitive values in plain text. Each one is redacted before a plan is kept anywhere.

| Where | The value becomes |
|---|---|
| `plan.json` and the report | `(sensitive, redacted by terragucci)`, wherever the value appears, also in an attribute the plan does not mark |
| `plan.txt` and the plan note | `(sensitive value)`, as the binary prints it, wherever the value appears |
| a policy denial or warning | redacted before it reaches the report, the note or the log |
| a write-only attribute | its version (`*_wo_version`); the value is never in the plan |
| an ephemeral value | not reported |

Plan digests are taken before redaction, so an approval binds the plan as planned. The policy engine reads the unredacted plan.

Forge tokens are removed from the environment the binary, Terragrunt and the policy engine start with ([the list](/terragucci/reference/environment/#forge-tokens)).

## Limits

| Case | What happens |
|---|---|
| a value not marked sensitive | it is in the plan, the note and the bucket like any other attribute; mark it, or keep the bucket private |
| a provider or a step that prints a value | it reaches the job log as printed |
| a passed secret in the plan job | the pull request's code runs there with it, as with the providers' credentials; a fork's pull request gets no plan job |
| the state | holds every secret its resources hold; reports and the bucket keep version ids only, and [`terragucci state export`](/terragucci/guides/export-a-state-version/) writes a version only to the machine of the person who runs it |

## Next

- [Sensitive values](/terragucci/reference/report/#sensitive-values) in the plan report.
- [Threat model](/terragucci/reference/threat-model/) for what each job can reach.

---

# Lock roots to a pull request

Source: https://intentius.io/terragucci/guides/lock-roots/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/lock-roots/.
Add `locks: plan` to terragucci.yml, run `npx terragucci config check --json` and `npx terragucci init`, and open a pull request with the result.
Tell me the status check to require in branch protection; do not change branch protection yourself.
Never comment `/terragucci lock` or `/terragucci unlock`.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

Each root an open change reaches is held for it. A second change that reaches a held root is refused, and the reply names the root and its holder.

These holds work across pull requests. The backend's state lock keeps two writers off one state file while a binary runs, a separate layer ([Locking and staleness](/terragucci/concepts/locking-and-staleness/)).

## Modes

| Setting | Roots are held | Forges |
|---|---|---|
| `locks: apply` (the default), with `apply.when: pull-request` | when the change applies before merge, or a writer comments `/terragucci lock` | GitHub, GitLab, Forgejo |
| `locks: plan` | from the first plan, and again on each push or `/terragucci plan` | GitHub, Forgejo |

Under the defaults, `apply.when: merge` and `locks: apply`, nothing is held.

`init` and `config check` refuse `locks: plan` on GitLab. The hold is taken by a job that runs from the default branch, and no merge request event on GitLab runs such a job. With [`apply.when: pull-request`](/terragucci/guides/apply-before-merge/) on GitLab, the [comments](/terragucci/guides/re-plan-from-a-comment/) schedule reads `/terragucci apply` and `/terragucci lock` on a merge request and takes the hold.

## Steps

1. Set the mode in `terragucci.yml`:

   ```yaml
   locks: plan
   ```

2. Check the file and write the pipeline again:

   ```bash
   npx terragucci config check
   npx terragucci init
   ```

   `init` adds the `pr-lock` job. It runs from the default branch on each event and comment, with no checkout of the change and no cloud role, and reads the change as data from git.

3. Open a pull request with the file and the pipeline, and merge it.

4. Require `terragucci/lock` in branch protection. Under `apply.when: merge` the hold gates nothing by itself; the required status keeps a refused change from merging.

5. Open a change. `terragucci/lock` passes and names the roots it holds. A second change that reaches one gets a failing `terragucci/lock` and a reply naming the root and the holder.

Nothing queues a refused change. Once the holder lets go, comment `/terragucci plan` on it to take the roots.

## Comments

| Comment, by anyone with write access | Does |
|---|---|
| `/terragucci lock` | holds every root the change reaches and applies nothing; the reply names the roots |
| `/terragucci unlock` | lets go of the change's roots; the reply names them |

On GitLab a Developer or above comments, and the comments schedule answers on its next run. Both need `apply.when: pull-request` or `locks: plan`.

## Release

| Event | Held roots |
|---|---|
| the holder merges or closes | released |
| `/terragucci unlock` on the holder | released |
| a push stops reaching a root, with `locks: plan` | that root is released |

The holds are kept in `_locks/tf-apply.json` on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle). A hold whose pull request merged or closed counts as released. A fork's pull request takes none.

## Reach

Outside plain roots, a change reaches more than the files it touches:

| Repo | Held |
|---|---|
| Terragrunt | the units it touches and every unit whose `dependency` or `dependencies` block names one, followed through; a change outside every unit, such as `root.hcl`, holds every unit |
| Atmos | the instances of each component it touches and their dependents; a stack manifest or `atmos.yaml` holds every instance |
| `synth`, such as CDK Terrain | every stack, for any file but Markdown |

A Markdown-only change holds nothing. [Locks](/terragucci/guides/apply-before-merge/#locks) has the full rules.

## Next

- [Release a state lock a killed job left](/terragucci/guides/release-a-state-lock/) frees a backend's state lock.
- [Plan locks](/terragucci/reference/pipeline/#plan-locks) lists what the `pr-lock` job has and never has.

---

# Manage the control repo with Terraform

Source: https://intentius.io/terragucci/guides/manage-the-control-repo-with-terraform/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/manage-the-control-repo-with-terraform/.
Read the terragucci.yml of the control repo I name and write a Terraform configuration that holds the same defaults and projects with terragucci_defaults and terragucci_project, plus the import blocks that adopt each of them.
Run `tofu plan` (or `terraform plan`) with the provider built as the page shows, and show me the plan. It must show no change other than the imports.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

A Terraform or OpenTofu configuration that owns the [control repo](/terragucci/concepts/control-repo/)'s `terragucci.yml`, as described in [Govern many repos from one place](/terragucci/guides/govern-many-repos/). The provider commits each change through the forge's API, so a plan shows which setting of which project moves before anything is written. `terragucci reconcile` reads what it wrote the same way it reads a hand-written config.

| Resource | Owns in `terragucci.yml` |
|---|---|
| `terragucci_defaults` | `defaults` |
| `terragucci_project` | one entry of `projects`, by its key |

Keys that no resource owns stay as they are, comments included. A resource whose key is already there refuses to overwrite it and names the `import` that adopts it.

## Before you start

| You need | Why |
|---|---|
| A control repo on GitHub, GitLab or Forgejo | the provider writes its `terragucci.yml` |
| A token that can push to the control repo's branch: `TERRAGUCCI_TOKEN`, or `GITHUB_TOKEN`, `GITLAB_TOKEN` or `FORGEJO_TOKEN` | each change is one commit through the API |
| Go 1.25 or later | you build the provider from the terragucci repository |
| Terraform or OpenTofu | to plan and apply |

## Steps

1. Build the provider.

   ```bash
   git clone https://github.com/intentius/terragucci
   cd terragucci/terraform-provider-terragucci
   go build -o "$HOME/.terragucci/provider/terraform-provider-terragucci" .
   ```

2. Point Terraform or OpenTofu at the build.

   Put this in a CLI configuration file, such as `~/.terragucci/dev.tfrc`:

   ```hcl
   provider_installation {
     dev_overrides {
       "intentius/terragucci" = "/home/you/.terragucci/provider"
     }
     direct {}
   }
   ```

   Use the full path of the directory you built into, and export `TF_CLI_CONFIG_FILE=$HOME/.terragucci/dev.tfrc`. Terraform and OpenTofu then load the provider from that directory without `init`, and print a warning saying so.

3. Describe the control repo.

   ```hcl
   terraform {
     required_providers {
       terragucci = {
         source = "intentius/terragucci"
       }
     }
   }

   provider "terragucci" {
     forge      = "github"
     repository = "acme/control"
   }

   resource "terragucci_defaults" "this" {
     settings = {
       binary = "tofu"
       gate   = "on-destructive"
     }
   }

   resource "terragucci_project" "infra" {
     key = "github.com/acme/infra"
     settings = {
       roots = ["envs/*/*"]
       drift = "17 4 * * *"
     }
   }
   ```

   `settings` takes the same keys as `terragucci.yml` ([keys](/terragucci/reference/config/#keys)), as an HCL object. The provider block also takes `url` for a forge that is not github.com, gitlab.com or codeberg.org, `api` when the API is not at the usual path under it, `branch` (default: the repository's default branch), `path` (default: `terragucci.yml`) and `token`.

4. Apply the configuration.

   ```bash
   tofu apply
   ```

   The control repo gets one commit per resource, such as `terraform: add terragucci_project github.com/acme/infra`. Destroying a resource takes its key out again; once no key is left, `terragucci.yml` is deleted.

5. Change a setting and plan.

   After you add `parallelism = 2` to the project's `settings`, `tofu plan` shows that one setting.

   ```text
     ~ resource "terragucci_project" "infra" {
           id       = "github.com/acme/infra"
         ~ settings = {
             + parallelism = 2
               # (2 unchanged attributes hidden)
           }
       }
   ```

   Each plan reads `terragucci.yml` from the forge first. A key someone edited or dropped by hand shows up as a change, which the next apply undoes.

6. Open the projects' pull requests.

   In a clone of the control repo, run [`reconcile`](/terragucci/guides/govern-many-repos/#steps):

   ```bash
   npx terragucci reconcile --config terragucci.yml --mode apply
   ```

   Each project whose pipeline changes gets a pull request.

## Adopt an existing file

Import each entry `terragucci.yml` already holds, then plan:

```hcl
  to = terragucci_defaults.this
  id = "defaults"
}

  to = terragucci_project.infra
  id = "github.com/acme/infra"
}
```

When the plan shows only the imports, the configuration matches the control repo.

## Next

- [Govern many repos from one place](/terragucci/guides/govern-many-repos/) covers what `reconcile` does with each project.

---

# Move resources between roots

Source: https://intentius.io/terragucci/guides/move-resources-between-roots/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/move-resources-between-roots/.
In this repo, move the resource blocks I name from their root to the root I name, write the migration file the page describes for that move, and open a pull request.
Tell me which roots the migration touches and what the plan job must prove. Do not run state commands or write any state.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

A resource moves between two roots' states through the same gate as an apply, and nothing is destroyed or created. `moved`, `import` and `removed` blocks work only inside one root; a migration file covers a move across roots.

| Step | Who | What happens |
|---|---|---|
| the pull request's plan job | terragucci | builds each affected root's new state in the job, plans every root against it, requires no change, and prints the digest |
| the apply job's wave 1, after the merge | terragucci | proves the move again and waits for an approval of that digest; no wave plans until it applies |
| `terragucci approve <name> --plan <digest>` | you | approves that digest and nothing else |
| wave 1 again, started by `terragucci approve` or the resume job | terragucci | takes each state's lock, refuses if a state moved since the plan, writes the new states, plans every root again and requires no change, and records each state's version id before and after |

The digest covers the file plus each root's state version and digest before the move and its new state's digest. A state written by anyone after the approval changes the digest, and wave 1 refuses with exit 4, naming the root.

State contents stay in your backend and the job's temporary directory. The record holds version ids and digests.

## Prerequisites

| You need | Why |
|---|---|
| Terraform or OpenTofu roots, CDK Terrain stacks, whose roots are `cdktf.out/stacks/<stack>` holding `cdk.tf.json`, or Terragrunt units | a unit is prepared by Terragrunt (`terragrunt run -- init`), and the job then reads and writes its state in the directory Terragrunt runs it in, with the inputs Terragrunt gives it; a move can go between two units, or between a unit and a plain root |
| An `s3` backend with `use_lockfile = true`, a `gcs`, `azurerm` or `local` backend, or a `pg`, `kubernetes`, `consul` or `http` backend, in every root the move touches | each state's lock is held while it is written; a root whose code has a `cloud` block, or another backend, is refused; a backend move also reads from a workspace or a state file |
| Versions kept: S3 bucket versioning, GCS object versioning, Azure blob versioning or `snapshot = true` | each version id before is the version to go back to; see [Find the state version an apply left](/terragucci/guides/find-a-state-version/). `pg`, `kubernetes`, `consul` and `http` keep none: the digest binds each state's contents, and the migration cannot be reverted |
| An apply identity that can write the states and take their locks | the rights the backend already needs |

Each backend's lock is taken as the backend takes it:

| Backend | Lock | Who writes the new state |
|---|---|---|
| `s3`, `gcs` | the lock object beside the state | the binary, with `state push -lock=false` while the job holds the lock |
| `azurerm` | a lease on the state blob | the job, under its lease, which keeps the binary out; a snapshot first when the backend sets `snapshot = true` |
| `pg`, `kubernetes`, `consul`, `http` | the backend's own: an advisory lock, a Lease, a session, the lock address | the binary, with `state push` under that lock, which refuses a state of another lineage or an older serial |
| A pipeline `terragucci init` wrote after the first migration file was added | on GitHub under `gate: never`, the apply jobs get `contents: write` to record the migration's gate on `chant/lifecycle` only then; `config check` and the plan job refuse a repo whose pipeline lacks it |

## Steps

1. Move the resource blocks in code. Cut `aws_sqs_queue.jobs` from `envs/dev/platform` and paste it into `envs/dev/queues` along with any variables and outputs it needs.

2. Write the migration file, `migrations/split-queues.yml`. Its name without `.yml` names the migration and its gate:

   ```yaml
   moves:
     - from: envs/dev/platform
       to: envs/dev/queues
       addresses:
         - aws_sqs_queue.jobs
   ```

   [Migration files](/terragucci/reference/migration-files/) lists what an address can name.

3. Open the pull request. The plan job proves the migration and prints its digest:

   ```text
   migration split-queues: moving aws_sqs_queue.jobs from envs/dev/platform to envs/dev/queues
   envs/dev/platform: no changes against its new state
   envs/dev/queues: no changes against its new state
   migration split-queues: every root plans with no change against its new state; digest jcs1-sha256:b298de39...
   ```

   A root that would change against its new state fails the job, which names each change. The roots' own plans in the same note still show the move as a destroy in one root and a create in the other: they plan against the states as they are, before the move is written.

4. Merge. Wave 1 proves it again and waits, exit 3:

   ```text
   migration split-queues waits for an approval of digest jcs1-sha256:b298de39.... Read the proof above, then approve it with:
     terragucci approve split-queues --plan jcs1-sha256:b298de39...
   ```

   Every later wave waits on wave 1, so no root applies against a state about to be rewritten.

5. Approve it from a checkout. `terragucci approve` finds the migration, prints what it moves and approves its digest, with `--sign` under `approval: sealed`. With a wave waiting too, name it: `terragucci approve split-queues`. A pull request review does not approve a migration, under any `approval:` mode.

6. Wave 1 runs again by itself: `terragucci approve` starts it with your forge token, or the resume job does on its next run with `apply.resume` set ([Resume after an approval](/terragucci/reference/pipeline/#resume-after-an-approval)). `init` writes the resume job whenever `apply.resume` is set, under `gate: never` too. On that run it writes the states and goes on to plan and apply the wave:

   ```text
   migration split-queues: approved by alice for this digest
   envs/dev/queues: wrote its new state
   envs/dev/platform: wrote its new state
   envs/dev/platform: version a7d36113-... before, 0dca9e05-... after
   envs/dev/queues: version none before, 3a695fbf-... after
   migration split-queues applied
   ```

   The root that gains resources is written first. A write that stops half way leaves a resource in both states, never in neither.

## Move a state to a new backend

Point the root's backend block at the new bucket or key, and add a migration naming where the state is now:

```yaml
# migrations/move-platform.yml
backends:
  - root: envs/dev/platform
    from:
      backend: s3
      config:
        bucket: acme-old-state
        key: envs/dev/platform.tfstate
        region: us-east-1
        use_lockfile: true
```

The plan job plans the root against the old backend's state with no change; the digest covers that state's version and digest. Wave 1 waits for the approval as for any migration. Once approved, it takes the lock files of the old and new state, checks that neither moved, then writes the state to the backend the code names, which must hold none for the root. The old state stays where it was; delete it once the move is verified.

A root on HCP Terraform, Scalr, OTF or env zero's backend moves the same way, with `backend: cloud` (or `remote`) naming the workspace, and the token in `TF_TOKEN_<host>`. The job holds the workspace's lock while it writes. State exported from another platform moves with `backend: file`. A `pg`, `kubernetes`, `consul` or `http` state moves with `backend` naming its type; the binary reads it with `state pull`. [Migration files](/terragucci/reference/migration-files/#backends) lists the keys.

## Estates

With [choudoufu](/terragucci/concepts/glossary/#choudoufu) as the binary, a root with a `live` block is an estate: it keeps no state file, and each resource carries its owner in two tags, `tofu-estate` and `tofu-address`. The same migration files move resources between estates and bring a state into one, through the same gate.

| File | Roots | The write |
|---|---|---|
| `moves` | both are estates | `choudoufu live-mv -from-estate` rewrites the tags of each resource, run in the root it moves to |
| `backends` | the root's code now has a `live` block in place of its backend block | `choudoufu live-import` reads the old state once and stamps the tags on each resource it verifies |

The proof reads the live system and writes nothing. Each root plans as its code stands, and every change it plans must be one the write removes: a destroy in the estate a resource leaves and a create in the one it joins, or a create of a resource the old state holds and the live system verifies. `live-mv -dry-run` must find each resource, and `live-import` without `-approve` must verify each one. The digest covers each root's planned changes, the live id of each resource and, for an adoption, the old state's version id and digest.

```text
migration carve-jobs: retagging aws_sqs_queue.jobs from the estate of mono to the estate of team
aws_sqs_queue.jobs: https://sqs.us-east-1.amazonaws.com/123456789012/jobs moves from estate mono to estate team
mono: 1 planned change, each one the retag removes
team: 1 planned change, each one the retag removes
migration carve-jobs: every change each root plans is one the retag removes; digest jcs1-sha256:5c0e91d2...
```

Once approved, wave 1 writes the tags, plans every root again and requires no change. An adoption holds the old state's lock file while it stamps, refuses if that state moved since the plan, and leaves it where it was, at the version the record names. A move from a root with a state to an estate is refused: adopt the state first, then move. `terragucci migrate revert` refuses both; move the resources back with a `moves` file the other way.

## Put a migration back

```bash
terragucci migrate revert split-queues
```

This writes `migrations/split-queues-revert.yml` from the record of `split-queues` on `chant/lifecycle`. The file names each root's version before the migration and the version it left. Open one pull request with that file and the reverted code of `split-queues`. The revert goes through the same proof and approval as any migration:

| Root | After the revert |
|---|---|
| one whose state the migration changed | the version it recorded before, read by its id, with the root's lineage and the next serial |
| one that had no state before | an empty state |
| one whose state moved past the version the migration left | refused: putting the older version back would undo that later change too |

A revert needs versions kept: a root with no version recorded before, or a local backend, has nothing to put back. An azurerm state with no blob versions is named by the snapshots the migration took before and after its write. A backend move is put back with a backend move the other way.

## Records

| Where | What it holds |
|---|---|
| `terragucci-report/migrations/<name>.json` in the job, and `<prefix>/<project>/migrations/<name>.json` in the [reports bucket](/terragucci/reference/reports-bucket/) | the moves, each root's version id and digest before and after, the proof and the plan after the write, the approver and the outcome; for estates, each resource's live id |
| `_gates/tf-migrate/done.jsonl` on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) | one line per migration that wrote its states: the digest, the approver, the result and each root's version before and after |
| the [audit trail](/terragucci/reference/audit-trail/) | a `migration` entry from that line, and the gate's request and approval |

A migration that applied never runs again. Its file can stay in the repo; changing it after it applied fails wave 1, so write a new file for a new move.

## Stop conditions

| Wave 1 says | Exit | What to do |
|---|---|---|
| a root would change against its new state | 1 | fix the code or the file so the move is exact, and push again |
| the states moved since the approval | 4 | read the new proof, and approve the new digest it prints |
| under the lock, a state is not the one planned | 4 | run wave 1 again: it plans from the states as they are |
| a state is locked | 1 | wait for the run that holds it, then run wave 1 again |
| after the write, a root plans changes | 1 | the states were written; the record names each version before, which [Find the state version an apply left](/terragucci/guides/find-a-state-version/#go-back-to-a-version) restores |

---

# Tell a chat channel when a wave stops

Source: https://intentius.io/terragucci/guides/notify-a-chat-channel/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/notify-a-chat-channel/.
Add a `notify:` block to terragucci.yml naming the secret SLACK_WEBHOOK_URL (or TEAMS_WEBHOOK_URL), run
`npx terragucci config check` and `npx terragucci init`, and open a pull request. Tell me which secret I must create.
Do not create the webhook or the secret, and never write a webhook address into any file.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

A message in your channel each time an apply job stops at a wave or the drift job finds a change. The message approves nothing; a person approves with `terragucci approve` from a checkout, which records the approval on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle). Under `approval: pr-review` an approving review of the pull request counts too.

| You want | You set up |
|---|---|
| a notice in Slack or Teams, and under `approval: pr-review` a link straight to the review that approves the wave | `notify:` and an incoming webhook for the channel. Nothing to install or host. |
| Approve and Decline buttons that record the approval on `chant/lifecycle` as the person who clicked | `terragucci relay`, in your own cloud ([Approve from Slack and Teams](/terragucci/guides/approve-from-chat/)) |

| The wave | Exit | The message says |
|---|---|---|
| waits for an approval | 3 | the wave, its roots, its plan digest, the [`terragucci approve`](/terragucci/reference/cli/#approve) command for that digest, and the run; under `approval: pr-review`, first a link to review the pull request ([below](#approve-from-the-message-by-review)) |
| is refused: its plans changed after approval | 4 | the wave, its roots, the outcome line, `npx terragucci approve wave-<k> --plan <digest>` for the new digest, and the run |
| fails, or the policy denies it | 1 | the wave, its roots, the outcome line, that there is nothing to approve, and the run |

## Prerequisites

| You need | Why |
|---|---|
| The [pipeline](/terragucci/getting-started/) | `init` maps the secret into the apply jobs |
| An incoming webhook for the channel | the apply job posts to it |
| A secret in your forge's store holding the webhook's address | the address is a credential: anyone holding it can post |

## Steps

1. Make a webhook for the channel.

**Slack**
       Turn on Incoming Webhooks in a Slack app and add a webhook to the channel. Copy its `https://hooks.slack.com/services/...` address.
**Teams**
       In the channel, add the Workflows template "Post to a channel when a webhook request is received", and copy the address it gives. terragucci posts an Adaptive Card, the body that template reads.

2. Store the address as a secret.

**GitHub**
       A repository secret under Settings, Secrets and variables, Actions.
**GitLab**
       A masked CI/CD variable. Mark it Protected so only default-branch pipelines, where the apply jobs run, see it.
**Forgejo**
       The same as GitHub; Forgejo keeps them under Settings, Actions, Secrets.

3. Name the secret in `terragucci.yml`. Use either key, or both:

   ```yaml
   notify:
     slack: SLACK_WEBHOOK_URL
     teams: TEAMS_WEBHOOK_URL
   ```

   The value is the secret's name. `config check` refuses an address.

4. Write the pipeline again and merge it.

   ```bash
   npx terragucci init
   ```

   The apply jobs get the secret as `TERRAGUCCI_SLACK_WEBHOOK` or `TERRAGUCCI_TEAMS_WEBHOOK`, and each runs `terragucci notify` when its wave stops. With a [drift schedule](/terragucci/guides/turn-on-drift-checks/), so does the drift job; no plan job gets it.

5. Read the next message.

**Slack**
   ```text
   terragucci: wave 2 of github.com/acme/infra waits for an approval
   Roots: envs/prod/app, envs/prod/db
   Digest: jcs1-sha256:9f2c...
   Approve: terragucci approve wave-2 --plan jcs1-sha256:9f2c...
   Run: https://github.com/acme/infra/actions/runs/42
   ```
**Teams**
       An Adaptive Card titled with the same first line. Its facts are Wave, Roots, Digest, Approve and Run. Its button opens the run.

| If the webhook | The job |
|---|---|
| answers 2xx | logs `terragucci notify: posted to Slack` (or Teams) |
| answers an error, or not within 10 seconds | logs the status and goes on; the wave's own exit code stands |

A comment that applies (`/terragucci apply`) posts the same messages from its job.

## Drift, with a Re-plan button

With a [drift schedule](/terragucci/guides/turn-on-drift-checks/), the drift job posts to Slack and Teams when its refresh-only plans find drift, or a root cannot be refreshed. A run that finds nothing posts nothing.

```text
terragucci: drift in github.com/acme/infra: 1 root changed outside Terraform
Drifted: envs/prod/app
Run: https://github.com/acme/infra/actions/runs/57
```

The Re-plan button opens the page where you run the check again under your own login; it holds no token and starts nothing itself.

| Forge | Re-plan opens |
|---|---|
| GitHub | the workflow's page, where Run workflow is |
| Forgejo | the workflow's runs, where Run workflow is |
| GitLab | the pipeline schedules, where each schedule has a run button |

The generic webhook gets no drift event: its events are a wave's.

## Approve from the message, by review

With [`approval: pr-review`](/terragucci/guides/approve-a-wave/#approve-by-review-approval-pr-review), a waiting wave's message opens with a link to the pull request's review page when an approving review of its head would approve the wave. The approval is still a person's own review on the forge, and it binds the plans the pull request's note recorded. The chat app holds no key and approves nothing.

```text
terragucci: wave 2 of github.com/acme/infra waits for an approval
Review and approve: pull request 12, then run the wave again
Roots: envs/prod/app, envs/prod/db
Digest: jcs1-sha256:9f2c...
Or approve: terragucci approve wave-2 --plan jcs1-sha256:9f2c...
Run: https://github.com/acme/infra/actions/runs/42
```

In Teams, the card's first button (Review and approve) opens the same page.

| Forge | The link opens | Given when |
|---|---|---|
| GitHub | the pull request's Files changed tab, where Review changes > Approve is | the wave's pull request has no approving review of its head, or a reviewer asked for changes, and its plan note has a digest for the wave |
| Forgejo | the pull request's Files changed tab, where Review > Approve is | the same |
| GitLab | the merge request, where Approve is | the same, and the merge request is still open (applied before it merges): GitLab takes no approval of a merged one |

A direct push gets no link, and neither does a refused wave or one the pull request's note has no digest for: no review of that head can approve those plans. The message then offers the approve command alone.

After the review, run the wave again: comment `/terragucci apply` on the pull request, or re-run the job ([Run the stage again](/terragucci/guides/approve-a-wave/#approve-with-chant)). The wave finds the approving review of the head and records it on `chant/lifecycle` with `via: pr-review`, then applies.

## Send events to your own webhook

`notify` can also post one JSON event to an HTTPS endpoint of yours and sign it with a key you hold. A chat bot, an incident tool or a relay that approves from chat can read it; the chat setup above needs none of this.

1. Store two secrets in your forge's store, as in step 2 above: the endpoint's address, and a random key of 32 bytes or more, for example from `openssl rand -hex 32`. Give the receiver the same key.

2. Name both in `terragucci.yml`. They can sit beside `slack` and `teams`.

   ```yaml
   notify:
     webhook: TERRAGUCCI_HOOK_URL
     webhook_key: TERRAGUCCI_HOOK_KEY
   ```

   `config check` refuses one without the other: an event is never sent unsigned.

3. Run `npx terragucci init` and merge. The apply jobs get the secrets as `TERRAGUCCI_WEBHOOK` and `TERRAGUCCI_WEBHOOK_KEY`.

4. Verify each request before reading it. The body is a [`terragucci.notify/v1`](/terragucci/reference/notify-event/) event.

   | Header | Holds |
   |---|---|
   | `X-Terragucci-Signature` | `sha256=` and the hex HMAC-SHA256 of the raw body with the key |
   | `X-Terragucci-Event` | `waiting`, `refused` or `failed` |
   | `X-Terragucci-Delivery` | the event's `id`, the same for each post of one wave's event about one digest; drop a repeat |

   ```js
   import { createHmac, timingSafeEqual } from "node:crypto";

   function verified(rawBody, header, key) {
     const want = Buffer.from("sha256=" + createHmac("sha256", key).update(rawBody).digest("hex"));
     const got = Buffer.from(header ?? "");
     return got.length === want.length && timingSafeEqual(got, want);
   }
   ```

The event carries the wave's outcome as the stage wrote it ([its fields](/terragucci/reference/notify-event/#fields)). It approves nothing, and the receiver's answer changes nothing: a webhook that fails or is slow is logged like the chat ones.

To approve from a chat click, [`terragucci relay`](/terragucci/guides/approve-from-chat/) does it without this event: the buttons carry the wave and its digest, and the relay checks who clicked.

## Next

- [Approve from Slack and Teams](/terragucci/guides/approve-from-chat/)
- [Approve a waiting wave](/terragucci/guides/approve-a-wave/)
- [Fix a refused wave](/terragucci/guides/fix-a-refused-wave/)

---

# Plan CDK Terrain stacks

Source: https://intentius.io/terragucci/guides/plan-cdk-terrain-stacks/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/plan-cdk-terrain-stacks/.
Add `synth: npm ci && npx cdktn synth` to terragucci.yml, add cdktf.out/ and node_modules/ to .gitignore,
run `npx cdktn synth` and then `npx terragucci init`, and open a pull request with the result.
Tell me which stacks init found and whether each one's backend keeps its state outside the job.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

A pipeline whose jobs run `cdktn synth` on their own checkout, then plan or apply the stacks it wrote to `cdktf.out/stacks/`. The synthesized files stay out of git.

## Prerequisites

| You need | Why |
|---|---|
| A [CDK Terrain](https://cdktn.io) app ([repository](https://github.com/open-constructs/cdk-terrain)) with `cdktf.json` at the repo root | `cdktn synth` reads it and writes one directory per stack |
| `cdktn` and `cdktn-cli` in `package.json`, such as 0.24.0 | the jobs run them with Node 22.23 from the terragucci image; cdktn 0.24 needs Node 22.19 or later |
| A remote backend in each stack, such as `S3Backend` | each job starts from a fresh checkout, so a local state file does not outlive it |
| `package-lock.json` committed | the job installs the app's packages with `npm ci` |
| The [pipeline](/terragucci/getting-started/) | `init` adds the synth step to it |

## Steps

1. Name the command in `terragucci.yml`:

   ```yaml
   synth: npm ci && npx cdktn synth
   ```

   It runs from the repo root. Any command that writes Terraform JSON or HCL works the same way.

2. Keep the output and the packages out of git:

   ```text
   cdktf.out/
   node_modules/
   ```

3. Synthesize once on your machine, then write the pipeline:

   ```bash
   npx cdktn synth
   npx terragucci init
   ```

   `init` finds each stack by the backend or provider in its `cdk.tf.json` and names `cdktf.out/stacks/<stack>` as a root. With no stacks on disk it stops and asks you to run the synth command first. Run both again when you add or remove a stack.

4. Read the step `init` wrote. It comes after the checkout and before any cloud credential:

**GitHub**
   ```yaml
   - name: Plan the roots the change reaches and write the plan report
     shell: bash
     run: |
       ...
       # synth in terragucci.yml: write the roots before reading them.
       ( set -e; npm ci && npx cdktn synth ) || { tg status terragucci/plan failure "the synth command failed"; echo "terragucci: the synth command failed" >&2; exit 1; }
       ...
       terragucci stage tf-plan --out terragucci-report --binary tofu --layers 'cdktf.out/stacks/dev,cdktf.out/stacks/prod' ...
   ```
**GitLab**
   ```yaml
   plan:
     script:
       - |-
         bash <<'PLAN' || exit $?
         ...
         # synth in terragucci.yml: write the roots before reading them.
         ( set -e; npm ci && npx cdktn synth ) || { tg status terragucci/plan failure "the synth command failed"; echo "terragucci: the synth command failed" >&2; exit 1; }
         ...
         terragucci stage tf-plan --out terragucci-report --binary tofu --layers 'cdktf.out/stacks/dev,cdktf.out/stacks/prod' ...
         PLAN
   ```
**Forgejo**
   The same step as GitHub, in `.forgejo/workflows/terragucci.yml`.

5. Open a pull request that changes one stack. The plan job's log shows the synth, the same synth on the base, and the plan of the stack that changed:

   ```text
   Generated Terraform code for the stacks: dev, prod
   synth at the base: npm ci && npx cdktn synth, on 3f2a91c0 in a checkout of its own
   affected: cdktf.out/stacks/prod differs from the base (cdk.tf.json differs)
   affected: 1 of 2 synthesized roots differ from origin/main, 0 dependents after them, 1 unchanged and not planned
   cdktf.out/stacks/prod: Plan: 0 to add, 1 to change, 0 to destroy.
   ```

   The plan note says how many stacks were left out:

   ```text
   > The synth command ran on the base (3f2a91c0) too: 1 synthesized root planned, 1 unchanged and not planned.
   ```

## Jobs

| Job | Runs the command | Then |
|---|---|---|
| check | yes | checks the format of the files git tracks, and validates each stack |
| plan, and a `/terragucci plan` re-plan | yes, on the pull request's head; `tf-plan` runs it again on the base | `tf-plan` plans the stacks whose output differs |
| each apply wave | yes | `tf-apply` plans the wave's stacks again and applies them behind the gate |
| `/terragucci apply` | yes, after it checks out the commit to apply | the same waves |
| tips | yes | `respond tips` opens the canary tip; see below |
| drift | yes | `tf-drift` refreshes every stack |

A command that fails ends the job; the plan job also sets `terragucci/plan` to failure. Without `synth`, a pipeline whose roots are not on disk stops with `found no roots`.

| Behavior | With `synth` |
|---|---|
| Which stacks a pull request plans | the ones the change affects; see below |
| Format check | the `.tf`, `.tofu` and `.tfvars` files git tracks, one directory at a time, so the packages `npm ci` installs are left out |
| Terragrunt | not supported: `init` refuses `synth` in a Terragrunt repo |
| [Ephemeral environments](/terragucci/guides/ephemeral-environments/#synthesized-roots) | the `ephemeral` job runs the synth command in the pull request's checkout, then copies the stacks `ephemeral.roots` names under keys suffixed `-pr-<n>` |
| [Linked roots](/terragucci/concepts/waves-and-approvals/#linked-roots) | a stack that reads another's state through a remote state data source, such as `DataTerraformRemoteStateS3`, plans on that stack's planned outputs, read from its `cdk.tf.json` |
| [State migrations](/terragucci/guides/move-resources-between-roots/) | a migration file names stacks by their roots, such as `cdktf.out/stacks/dev`; `tf-plan` proves it against each stack's `cdk.tf.json` after the synth, and wave 1 writes it once approved. Move the construct in the app in the same change, keeping its id, so the address in the other stack is the same |

## Stack edits

The stacks' files are the app's output. Git does not hold them and the next synth rewrites them, so a change a response would make to them belongs in the app.

| Feature | With `synth` |
|---|---|
| Tips | the canary tip, which edits `terragucci.yml`; the job log says the provider pin and lock file tips are left out |
| `respond.drift: pull-request`, the default, with a `drift` schedule | a config error: set `respond.drift` to `attribute` or `off` |
| `respond.drift: attribute` | `tf-drift` names who changed each attribute in the drift issue; no pull request follows, and the drift job's log says why |
| `rollouts`, or `terragucci rollout` in the repo | a config error: move the pin in the app |
| [`generate`](/terragucci/guides/generate-root-files/#with-synth) | a config error naming the backend constructs: set the backend, providers and `required_version` in the app |
| A [control repo](/terragucci/concepts/control-repo/)'s rollout | a project with `synth` is listed as refused, and the other projects roll out |

## Planned stacks

The stacks are not in git, so no diff names them. `tf-plan` compares what the app writes at the base with what it writes at the head:

| Step | What happens |
|---|---|
| Base | `tf-plan` checks out the merge base of the target branch in a directory of its own and runs the synth command there |
| Compare | each stack's directory (`cdk.tf.json`, its lock file, its assets) and every local module it calls outside it, file by file |
| Plan | a stack whose files differ, a new stack, a removed stack, and any stack that reads one of their states |
| Leave out | every other stack; the note counts them |

| When | Then |
|---|---|
| The synth command fails on the base | every stack plans, and the note says the base could not be synthesized |
| The merge base cannot be found | every stack plans, and the note says why |
| No stack differs | nothing plans, and the note says the change reaches no root |

| The base's synth | |
|---|---|
| Runs | in `tf-plan`, after the plan job's credentials are set |
| Code | the target branch, which the apply jobs already run |
| Cost | a pull request runs the synth twice, so `npm ci` takes its time twice |

## Next

- [terragucci.yml keys](/terragucci/reference/config/)
- [Approve a waiting wave](/terragucci/guides/approve-a-wave/)

---

# Query the estate with SQL

Source: https://intentius.io/terragucci/guides/query-with-sql/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/query-with-sql/.
Write the terragucci query command that lists the resources of type aws_sqs_queue changed in the last 7 days with their approvers, for this repo's reports bucket, and run it. Do not create or print credentials.
Read only. Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

Which queues changed this week, and who approved each change? The estate page shows one resource at a time. `terragucci query` answers across every project with one SQL statement. It reads the files your runs already wrote to the [reports bucket](/terragucci/guides/keep-reports-in-a-bucket/) and runs the statement on the SQLite built into Node.js. There is no server and no database to run.

## Result

```bash
npx terragucci query "SELECT address, actions, approver, finished FROM history
  WHERE type = 'aws_sqs_queue' AND julianday(finished) >= julianday('now', '-7 days')
  ORDER BY finished"
```

```text
address             actions  approver      finished
------------------  -------  ------------  ------------------------
aws_sqs_queue.jobs  create   approver-one  2026-10-09T05:15:39.686Z
aws_sqs_queue.jobs  update   approver-two  2026-10-09T05:15:54.614Z
(2 rows)
```

Each approver is the one the [audit trail](/terragucci/reference/audit-trail/) records for the wave that applied the change.

## Tables

| Table | One row per | Read from |
|---|---|---|
| `inventory` | resource a root holds, as its newest applied wave left it | each project's `inventory.json` |
| `changes` | resource an applied wave changed | each project's `changes.json` |
| `history` | change, with its wave's `approver` and `approval` entry id | `changes.json` joined to `audit.jsonl` |
| `audit` | audit trail entry | `audit.jsonl` |
| `edges` | root whose state another root reads | each project's `edges.json` |

Columns keep the field names of the [JSON the bucket holds](/terragucci/reference/report-schema/#the-index-and-the-estate-page), with `project` added.

- `actions` joins a change's actions with `+`, such as `create` or `move+update`.
- `attributes` and `audit.detail` hold JSON. Read them with `json_each` and `json_extract`.
- `approver` is null when no gate held the wave, or when the audit trail has no entry for it.
- `commit` is an SQL keyword, so quote it: `"commit"`.
- Times are ISO 8601 text. Compare them with `julianday()`.

No table holds an attribute's value, because no file in the bucket does.

## Steps

1. Keep [reports in a bucket](/terragucci/guides/keep-reports-in-a-bucket/), and run `terragucci audit` on a schedule for the `history` approvers and the `audit` table.

2. Use Node.js 22.13 or later, and give your shell read access to the bucket in the variables [Reports](/terragucci/reference/environment/#reports) lists.

3. From the repo's root, run `npx terragucci query "<statement>"`. Outside the repo, add `--bucket` and `--bucket-prefix`. Add `--json` for the rows as JSON.

The query reads only. A statement must begin with `SELECT`, `WITH` or `VALUES`. The database lives in memory and refuses writes.

## Next

- [CLI reference](/terragucci/reference/cli/#query) for the flags and exit codes.
- [See every project in one page](/terragucci/guides/see-every-project/) for the same files as a page.

---

# Read the audit trail

Source: https://intentius.io/terragucci/guides/read-the-audit-trail/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/read-the-audit-trail/.
Download audit.jsonl from the top of my reports prefix with a read-only identity and tell me, for the project and wave I name,
who approved it, which digest, when it applied, and any override or refusal, each with its evidence link.
Read only: do not run `terragucci audit` without `--check`, and write nothing to the bucket.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

Each approval, apply and override in your projects, traced to the person behind it and linked to its evidence.

## Prerequisites

| You need | Why |
|---|---|
| [Reports in a bucket](/terragucci/guides/keep-reports-in-a-bucket/) | the record and the wave reports it reads live there |
| A `terragucci audit` step in the [estate job](/terragucci/guides/see-every-project/), before `terragucci estate` | the step writes the record ([Write it](/terragucci/reference/audit-trail/#write-it)) |
| A read-only identity on the bucket, and `jq` | to fetch and query the record |

## Storage

The record is three objects at the top of your reports prefix, beside `estate.html`:

| Object | Holds |
|---|---|
| `audit.jsonl` | one entry per line: every approval, apply, override, refusal, lock release, state export and migration |
| `audit.html` | counts by kind, each project's ledger state, and the newest 1000 entries with their evidence links |
| `audit.json` | the summary the estate page reads to link `audit.html` |

terragucci builds it from two sources it does not hold itself: the approval ledger on each repo's [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) branch, and the `tf-apply` wave reports in the bucket.

## Steps

1. Open the page, or fetch the record. The `terragucci audit` step's log ends with a signed link to `audit.html`; for the lines, use the store's own CLI:

   ```bash
   aws s3 cp s3://acme-terragucci/reports/audit.jsonl .
   ```

2. Find the approvals of a wave. On an `approval` entry, `who` names the approver and `digest` the plan digest it binds; `result` says how it was signed:

   ```bash
   jq -c 'select(.project == "github.com/acme/network" and .what == "wave-2") | {at, kind, who, digest, result}' audit.jsonl
   ```

   ```text
   {"at":"2026-10-08T09:12:44.000Z","kind":"approval","who":"dana","digest":"sha256:4be1...","result":"unsigned"}
   {"at":"2026-10-08T09:20:03.000Z","kind":"apply","who":"dana","digest":"sha256:4be1...","result":"applied"}
   ```

   Under `approval: ledger`, `who` is the name the approver gave and `detail.committed_by` is who pushed the line. Under `sealed`, `detail.signer` is the key's owner, checked against the signers file at base ([what each mode proves](/terragucci/reference/audit-trail/#kinds-and-results)).

3. Match the apply to its approval. On the `apply` entry, `detail.approval` holds the `id` of the approval it applied under:

   ```bash
   jq -c 'select(.kind == "apply") | {at, project, what, who, digest, approval: .detail.approval, commit: .detail.commit}' audit.jsonl
   ```

   `evidence.url` on each entry opens the commit on `chant/lifecycle` that added the approval, or the wave's `report.html`.

4. List the overrides. `who` is the person who let the plan through, and `detail.reason` why:

   ```bash
   jq -r 'select(.kind == "override") | [.at, .project, .what, .who, (.detail.rules | join(",")), .detail.reason] | @tsv' audit.jsonl
   ```

   The wave that applied under it lists the root in `detail.overrides` on its `apply` entry.

5. List what did not go out:

   ```bash
   jq -r 'select(.kind == "refused" or .result == "failed") | [.at, .project, .what, .result, .evidence.url // .evidence.key] | @tsv' audit.jsonl
   ```

   On a `refused` entry, `result` gives the reason, such as `changed-after-approval`; `detail` names the roots that moved or the rules that denied.

## Check the record

`--check` rebuilds the entries from the ledgers and reports and writes nothing. It exits 1 naming each entry the record lacks:

```bash
npx --yes @intentius/terragucci audit --check
```

A removed ledger line shows as `approval-revoked` or `override-revoked`, with the commit that removed it; the record keeps the line it revoked.

## Next

- [The audit trail](/terragucci/reference/audit-trail/) lists every kind, field and retention rule.
- [Query the estate with SQL](/terragucci/guides/query-with-sql/) answers questions over the reports and the audit trail in SQL.

---

# Release a state lock a killed job left

Source: https://intentius.io/terragucci/guides/release-a-state-lock/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/release-a-state-lock/.
A plan or apply in this repo fails because the state of a root I name is locked. Read the lock for that root (a lock file, a gcs lock object, or an azurerm blob lease) and tell me its ID, who took it and when, and which of the forge's runs that began before then are still running.
Do not run `terragucci unlock-state`, `force-unlock` or any state command, and do not delete the lock file.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

When a runner kills a job mid-apply (a timeout or a cancelled run), the binary never releases its hold on the state. The root's next plan then waits until its timeout and fails. `terragucci unlock-state` runs `force-unlock` with checks a hand run lacks:

| Check | What it guards against |
|---|---|
| no run that began before it was taken is alive | freeing state that a job still applying holds, so that two applies write one state |
| an approval of its ID | a release only the person typing agreed to, or one of a newer hold taken since |
| a record on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) | a release nobody can find later; the [audit trail](/terragucci/reference/audit-trail/) lists it as `unlock` |

It reads the lock where the backend keeps it:

| Backend | Lock | ID |
|---|---|---|
| `s3` with `use_lockfile = true` | the lock file `<key>.tflock` | the ID in the file |
| `gcs` | the lock object `<prefix>/<workspace>.tflock` | the object's generation, as the binary prints it |
| `azurerm` | a lease on the state blob, with the lock info in its metadata | the lease's ID |
| [GitLab-managed state](#gitlab-managed-state) | GitLab's lock on the state | the ID in the lock |

A comment never runs it. With [`binary: choudoufu`](/terragucci/concepts/glossary/#choudoufu) and a record store, a killed job holds no lock, so there is none to release ([locking with choudoufu](/terragucci/concepts/locking-and-staleness/#with-choudoufu)).

## Free the state

1. Find the root. The failed job's log names the state and the ID:

   ```text
   Error: Error acquiring the state lock
   Lock Info:
     ID:        1f0c6a52-...
     Path:      acme-state/envs/prod/app.tfstate
     Operation: OperationTypeApply
     Who:       root@runner-7
     Created:   2026-10-09 18:02:11.420 +0000 UTC
   ```

2. Make sure the job that took it has ended, and stop it on the forge if not.

3. In a checkout of the default branch, with the backend's credentials and the forge token in the variable `token_env` names (`FORGEJO_TOKEN`, `GITHUB_TOKEN` or `GITLAB_TOKEN` by default), run:

   ```bash
   npx terragucci unlock-state envs/prod/app
   ```

   A run that began before the hold and is still running may be the holder; then nothing is freed, and the command exits 1 naming the run. With no such run, it records the release as waiting and prints the command that approves it:

   ```text
   terragucci unlock-state: envs/prod/app: releasing lock 1f0c6a52-..., OperationTypeApply by root@runner-7 at 2026-10-09T18:02:11.420Z waits for an approval of digest jcs1-sha256:6d2b.... Approve it with:
   terragucci unlock-state:   terragucci approve unlock envs/prod/app --plan jcs1-sha256:6d2b...
   ```

4. Whoever approves your waves runs that command, with `--sign` under `approval: sealed`. The approval names this ID and no other.

5. Run `npx terragucci unlock-state envs/prod/app` again. It asks the forge about the runs once more and frees the state with the binary's `force-unlock` of that ID. The release goes in `_gates/tf-unlock/done.jsonl` with the approver and the person who ran it.

6. Rerun the wave or push the next change; its plan takes the state as usual.

## GitLab-managed state

GitLab has no call that reads a lock, so `unlock-state` asks for it. A held lock answers with its ID, the GitLab user who took it and when. A free lock is taken and given back at once. The release is a `DELETE` of that ID on the lock endpoint, which GitLab refuses when another lock holds the state.

| You need | Why |
|---|---|
| `lock_address` and `unlock_address` in the block, or `TF_HTTP_LOCK_ADDRESS` and `TF_HTTP_UNLOCK_ADDRESS` | without them the backend takes no lock |
| `TF_HTTP_USERNAME`, and a personal access token with the Maintainer role in `TF_HTTP_PASSWORD` | GitLab lets Maintainers lock and unlock state |

The log names the lock endpoint:

```text
terragucci unlock-state: app: https://gitlab.example.com/api/v4/projects/42/terraform/state/app/lock holds lock 1f0c... by deploy-bot at 2026-10-09T18:02:11.420Z
```

Flags and exit codes are on [CLI commands](/terragucci/reference/cli/#unlock-state).

---

# Run steps around a stage

Source: https://intentius.io/terragucci/guides/run-steps/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/run-steps/.
Propose the steps block for terragucci.yml that runs my repo's checks before each plan, with on_failure: approve on any check that should hold a wave for a person rather than fail it.
Add it to terragucci.yml, run `npx terragucci config check`, and open a pull request. Tell me that the steps take effect once it merges, and why.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

On every forge, your commands run inside the job that already runs each root's `init`, `plan` and `apply`. The plan note and the report list every step that ran:

```text
**Steps (2):**

| Root     | When        | Step   | Result                         |
|----------|-------------|--------|--------------------------------|
| envs/app | before-plan | tfvars | passed                         |
| envs/app | after-plan  | verify | asks for an approval, exit 1   |
```

## Prerequisites

| You need | Why |
|---|---|
| The [pipeline](/terragucci/getting-started/) | the stages run the steps |
| Whatever your commands call, in the job's image | the steps run in the job's container; [your own image](#run-the-jobs-in-your-own-image) can carry it |

## Steps

1. List the steps in `terragucci.yml`:

   ```yaml
   steps:
     - name: tfvars
       run: ./scripts/write-tfvars.sh > step.auto.tfvars
       before: plan
     - name: verify
       run: cosign verify-blob --key cosign.pub --signature module.sig module.tgz
       after: init
       roots: ["prod/*"]
       on_failure: approve
   ```

   | Key | Meaning |
   |---|---|
   | `run` | a shell command, run in the root's directory |
   | `before` or `after` | one of them, naming `init`, `plan`, `apply` or `drift` |
   | `name` | what the log, the note and the report call it; the command's first line when unset |
   | `roots` | globs of the roots it runs for; every root when unset |
   | `on_failure` | `fail`, the default, or `approve` |

2. Check the file, then merge it:

   ```bash
   npx terragucci config check
   ```

   Later changes pick them up once this one merges ([why](#steps-are-read-at-base)).

## Step timing

| Job | Runs the steps of |
|---|---|
| plan, and a `/terragucci plan` re-plan | `init`, then `plan`, for each root the change reaches |
| `apply-wave-<k>`, and `apply-comment` with `apply.when: pull-request` | `init` and `plan` for each root of the wave, then `apply` once the gate lets the wave through |
| drift | `init`, then `drift` around the refresh-only plan |
| check | none |

A root's steps run in this order: `before-init`, `init`, `after-init`, `before-plan`, the plan, `after-plan`. On an apply wave `before-apply`, the apply and `after-apply` follow once the gate decides. Roots that plan side by side run their steps side by side.

Each step gets the job's environment minus its forge tokens (as the binary does), plus these:

| Variable | Value |
|---|---|
| `TG_STAGE` | `tf-plan`, `tf-apply` or `tf-drift` |
| `TG_STEP` | the moment, such as `before-plan` |
| `TG_ROOT` | the root's path from the repo |
| `TG_REPO` | the checkout's path |
| `TG_PLAN_FILE` | after a plan and before an apply: the saved plan, which `tofu show -json "$TG_PLAN_FILE"` reads |

A step's output goes to the job log with each line prefixed by the root and step name. The report keeps its name, moment, result, exit code and time, never its output.

## In a Terragrunt repo

A wave of units plans with one `run --all` and applies with another, so each moment comes once per wave. A step then runs in turn in each unit directory its `roots` globs match, and `TG_ROOT` names the unit:

| Moment | Runs |
|---|---|
| `before-init`, `before-plan` | before the wave's `run --all plan`; on a pull request's plan a unit whose step fails is refused and the rest plan |
| `after-plan` | after it, with `TG_PLAN_FILE` the unit's saved plan; `on_failure: approve` holds the wave at its gate |
| `before-apply`, `after-apply` | around the `run --all apply`, for the units that change |
| `before-drift`, `after-drift` | around the drift job's refresh-only `run --all` |

Terragrunt inits each unit inside `run --all plan` and leaves no gap before its plan. `after: init` is therefore refused; use `before: plan`. A provisional preview of dependents runs no steps.

## Step failures

| `on_failure` | A non-zero exit |
|---|---|
| `fail`, the default | fails the root, and its later steps do not run. On a plan the root is refused; on an apply wave nothing in the wave applies. A failure after the apply fails the job, though the root has applied |
| `approve` | holds the root's wave at its gate. The steps after it still run. The wave waits for an approval of its set digest, whatever `gate` says, and the plan note shows the wave as one that waits |

An `approve` step must run before the gate decides, so `config check` accepts it only around `init` or `plan`.

The wave waits through the same ledger as every other gated wave: [`terragucci approve`](/terragucci/reference/cli/#approve) of its digest on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle), under the [approval mode](/terragucci/guides/approve-a-wave/#approval-modes) at base. A wave that changes nothing applies nothing, so it never waits. With `waves.jobs`, a share job whose `approve` step fails applies nothing unless the wave's job decided under an approval.

## Steps are read at base

Each run reads the steps from `terragucci.yml` at its base, which the change cannot alter:

| Run | Reads the steps at |
|---|---|
| a pull request's plan | the target branch |
| an apply after a merge | the applied commit's first parent, as the approval mode is read |
| `apply.when: pull-request` | the base the pull request applies onto |
| drift | the default branch, which it checks out |

A change therefore cannot add, edit or remove a step that runs with its apply credentials, nor drop an `approve` step to skip the gate. An unreadable base file fails the stage when the checkout names steps; when it names none, no steps run. The [threat model](/terragucci/reference/threat-model/#steps) has the rest.

## Run the jobs in your own image

Build your own image `FROM` terragucci's when a step needs a tool it lacks, and set `image`. terragucci's images are Debian, so tools come from `apt-get`:

```dockerfile
FROM ghcr.io/intentius/terragucci-tofu:<the tag init names>
RUN apt-get update && apt-get install -y --no-install-recommends jq
```

```yaml
image: registry.example.com/infra/terragucci-tofu:1
```

`npx terragucci init` then writes it into each job. Since it must keep terragucci and the binary, build it from the tag the pipeline's header names and rebuild it on each terragucci upgrade. One image serves every job: the plan job plans every root a change reaches, so a root cannot have an image of its own.

## Next

- [Approve a wave](/terragucci/guides/approve-a-wave/)
- [The plan report](/terragucci/reference/report/)
- [terragucci.yml keys](/terragucci/reference/config/)

---

# Keep each environment's roles to its own state

Source: https://intentius.io/terragucci/guides/scope-state-access/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/scope-state-access/.
In this repo, add oidc.roles to terragucci.yml with one glob per environment the roots show, using placeholder role ARNs, and run `npx terragucci config check`.
Write the IAM policy each role needs, from the state keys config check lists, as a file for me to review. Open a pull request.
Do not create a role, change a trust policy or touch a state.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

Each root runs every command, steps included, with its environment's roles. In dev those are the dev roles, which your IAM policies limit to dev's state keys.

| Where | What it shows |
|---|---|
| `terragucci config check` | each role, the roots that take it and the state keys it needs; a warning for each role that reaches another environment's state |
| the plan and apply jobs | `TERRAGUCCI_ROOT_ROLES`, the stage's roles by glob; each root's binary gets its role as `AWS_ROLE_ARN` |
| the [threat model](/terragucci/reference/threat-model/#state-access-per-environment) | what a role per environment stops, and what it does not |

## Prerequisites

| You need | Why |
|---|---|
| [`oidc`](/terragucci/reference/pipeline/#credentials) set up with an IAM OIDC provider for your forge | each role trusts the forge's token, as `plan_role` and `apply_role` do |
| Roots with an `s3` backend whose `bucket` and `key` are in the code | `config check` reads the state keys from the backend blocks |
| Plain roots | a Terragrunt repo sets `terragrunt.credentials` instead, which works the same way per unit |

## Steps

1. Name a pair of roles per environment, by the roots' paths. The first glob a root matches wins; a root no glob matches takes `plan_role` and `apply_role`, which you can leave out when every root matches a glob.

   ```yaml
   oidc:
     roles:
       "envs/dev/**": { plan: arn:aws:iam::444455556666:role/dev-plan, apply: arn:aws:iam::444455556666:role/dev-apply }
       "envs/prod/**": { plan: arn:aws:iam::111122223333:role/prod-plan, apply: arn:aws:iam::111122223333:role/prod-apply }
   ```

2. Run `terragucci config check`. It lists each role with the state keys its roots' backends name:

   ```text
   terragucci.yml: ok
   approval: ledger (the default)
   state access:
     arn:aws:iam::444455556666:role/dev-plan (plan, envs/dev/**): s3://acme-state/dev/app.tfstate
     arn:aws:iam::444455556666:role/dev-apply (apply, envs/dev/**): s3://acme-state/dev/app.tfstate
     arn:aws:iam::111122223333:role/prod-plan (plan, envs/prod/**): s3://acme-state/prod/app.tfstate
     arn:aws:iam::111122223333:role/prod-apply (apply, envs/prod/**): s3://acme-state/prod/app.tfstate
   ```

3. Scope each role's policy to those keys. The plan role only reads. With `use_lockfile` the apply role also writes and deletes the lock file beside the state it reads and writes:

   ```json
   {
     "Version": "2012-10-17",
     "Statement": [
       { "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::acme-state", "Condition": { "StringLike": { "s3:prefix": ["prod/*"] } } },
       { "Effect": "Allow", "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"], "Resource": ["arn:aws:s3:::acme-state/prod/app.tfstate", "arn:aws:s3:::acme-state/prod/app.tfstate.tflock"] }
     ]
   }
   ```

   Trust each pair as you trust `plan_role` and `apply_role`. Plan trusts the pull-request and default branch subjects; apply trusts only the default branch's.

4. Read the warnings. `config check` prints them on stderr and still exits 0:

   | Warning | What to do |
   |---|---|
   | a role is the role of two environments | give each environment a pair of its own |
   | a root reads the state of another environment's root | the reading root's roles need that state key too; move the output it needs, or grant that one key read-only and accept the reach |
   | a root matches no glob and `oidc` names no pair | add a glob for it, or set `plan_role` and `apply_role` |

5. Run `terragucci init` and merge the new pipeline. The plan and apply jobs fetch the token as before and carry the stage's roles; the stage sets `AWS_ROLE_ARN` for each root. A state migration's reads and writes, and the state version an apply records, use the root's role too.

## GCP and Azure

`oidc.gcp.roles` gives a service account pair per glob, and `oidc.azure.roles` a client pair. A root no glob matches takes the job's own pair (`plan_service_account` and `apply_service_account`, `plan_client_id` and `apply_client_id`), which stay required.

```yaml
oidc:
  gcp:
    workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/forge/providers/ci
    plan_service_account: tg-plan@acme.iam.gserviceaccount.com
    apply_service_account: tg-apply@acme.iam.gserviceaccount.com
    roles:
      "envs/prod/**": { plan: prod-plan@acme.iam.gserviceaccount.com, apply: prod-apply@acme.iam.gserviceaccount.com }
  azure:
    tenant_id: 7d2c0b4e-0000-4000-8000-00000000a2e1
    subscription_id: 00000000-0000-4000-8000-000000000001
    plan_client_id: client-plan
    apply_client_id: client-apply
    roles:
      "envs/prod/**": { plan: client-prod-plan, apply: client-prod-apply }
```

| Cloud | Each root's binary gets | The identity needs |
|---|---|---|
| GCP | `GOOGLE_APPLICATION_CREDENTIALS`, a copy of the job's credentials file that impersonates the root's service account | Workload Identity User for the pool's principal, as the job's service accounts have |
| Azure | `ARM_CLIENT_ID`, the root's client | a federated credential for the job's subjects |

`config check` lists each service account with the `gcs` states its roots keep, and each client with the `azurerm` ones, and warns as it does for AWS roles. Grant each identity its environment's bucket prefix or container alone.

## Limits

A job's token can be exchanged for every role whose trust names the job's subject, so code in a root that reads the token file can assume another environment's role itself. The roles keep each root's own runs to its environment's state, and keep a backend pointed at the wrong key from reading it; they do not separate two environments' code planned in one job. The [threat model](/terragucci/reference/threat-model/#state-access-per-environment) has the full table.

## Next

- [Credentials](/terragucci/reference/pipeline/#credentials) for the trust each role needs on each forge.
- [`config check`](/terragucci/reference/cli/#config-check) for every warning.

---

# See every project in one page

Source: https://intentius.io/terragucci/guides/see-every-project/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/see-every-project/.
In this control repo, add the scheduled estate job the page gives for my forge,
and write the IAM policy for bucket <bucket> as a file for me to review. Open a pull request.
Do not create the role, the bucket or any secret.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

A scheduled job rebuilds `estate.html` and `estate.json` at the top of your reports prefix. Nothing is hosted, since the page is an object in your bucket or Blob container; a signed link to it (an S3 presigned URL, a GCS V4 signed URL or an Azure user delegation SAS) ends the job's log.

| The page shows | From |
|---|---|
| projects, waves waiting, projects drifted, roots failed | four counts at the top |
| each waiting wave and how long it has waited | the newest commit that ran `tf-apply` |
| roots applied under a [policy override](/terragucci/reference/policy/#overriding-a-denial), when there are any | a fifth count, and the apply wave that applied them |
| per project: latest plan, latest drift check, apply waves | each project's `index.json` |
| each project's roots by wave, an arrow from each root to the roots that read its state, dashed between projects, and a list of the reads between projects | the run view of each project's newest applied commit, `runs/<commit>/run.json` |
| the 20 newest runs | every project's `index.json` |
| the resources each root holds, by project, root and type, with a filter box | each project's `inventory.json` |
| each resource's change history, on `history.html` | each project's `changes.json`, and `audit.jsonl` for the approvers |
| each root's state versions, newest first, or that its bucket keeps none | each project's `states.json` |
| each root that reads another root's state, with its last plan against the producer's last apply | each project's `edges.json` |
| a link to the [audit trail](/terragucci/reference/audit-trail/), when the job writes one | `audit.json` beside the page |
| the four DORA metrics per project and for the estate, week by week, also in `dora.json` | `audit.jsonl` and each project's `index.json` |

The page reads only the files above and never a report or a plan.

In a Terragrunt repo the graph groups units into the waves their apply cut from `terragrunt find`; an edge links a unit to each unit whose `dependency` or `dependencies` block names it. A read between projects is a `terraform_remote_state` block in one project whose bucket and key name the state another project's root holds in its backend block. Under [choudoufu](/terragucci/concepts/glossary/#choudoufu), a root's state is its estate's records, and a `terraform_estate_outputs` read of an estate another project owns is such a read. A project shows on the graph once one of its applies wrote a run view, which needs `reports.bucket` in its own config. The graph and the [run view](/terragucci/concepts/waves-and-approvals/#the-run-view) are inline SVG, so the page loads no script.

## Prerequisites

| You need | Why |
|---|---|
| [Reports in a bucket](/terragucci/guides/keep-reports-in-a-bucket/) for every project you want on the page | the page reads each project's report index there |
| A repo to run the job in: your [control repo](/terragucci/concepts/control-repo/), or any repo whose `terragucci.yml` names the bucket | the job writes the page to that bucket |

## Steps

1. Pick where the projects come from.

   | Run from | Projects on the page | Read from | Page written to |
   |---|---|---|---|
   | a control repo | its `projects:` | each project's own `reports` | `defaults.reports` |
   | one repo | every project in the top `index.json` | that repo's `reports` | the same bucket |

   For projects in other accounts:

   | Option | Set up |
   |---|---|
   | one central bucket | every project's `reports.bucket` names it, each writing with a `reports.role` of its own |
   | a bucket per account | the project's `reports` in the control repo names its bucket and a `role` that can read it |

2. Give the job an identity.

   | The job | What |
   |---|---|
   | reads | the indexes, each apply wave's report, the audit trail |
   | writes | the page and its files, the audit trail (step 5) |
   | signs | the link |

**AWS**
   ```json
   {
     "Version": "2012-10-17",
     "Statement": [
       { "Effect": "Allow", "Action": "s3:GetObject", "Resource": ["arn:aws:s3:::acme-terragucci/reports/*index.json", "arn:aws:s3:::acme-terragucci/reports/*inventory.json", "arn:aws:s3:::acme-terragucci/reports/*changes.json", "arn:aws:s3:::acme-terragucci/reports/*states.json", "arn:aws:s3:::acme-terragucci/reports/*edges.json", "arn:aws:s3:::acme-terragucci/reports/*/runs/*/run.json", "arn:aws:s3:::acme-terragucci/reports/estate.html", "arn:aws:s3:::acme-terragucci/reports/history.html", "arn:aws:s3:::acme-terragucci/reports/audit.json", "arn:aws:s3:::acme-terragucci/reports/audit.jsonl", "arn:aws:s3:::acme-terragucci/reports/*/tf-apply-wave-*/report.json"] },
       { "Effect": "Allow", "Action": "s3:PutObject", "Resource": ["arn:aws:s3:::acme-terragucci/reports/estate.html", "arn:aws:s3:::acme-terragucci/reports/estate.json", "arn:aws:s3:::acme-terragucci/reports/history.html", "arn:aws:s3:::acme-terragucci/reports/history.json", "arn:aws:s3:::acme-terragucci/reports/dora.json", "arn:aws:s3:::acme-terragucci/reports/audit.jsonl", "arn:aws:s3:::acme-terragucci/reports/audit.html", "arn:aws:s3:::acme-terragucci/reports/audit.json"] }
     ]
   }
   ```
**GCP**
   A service account with `roles/storage.objectUser` on the bucket and `roles/iam.serviceAccountTokenCreator` on itself.
**Azure**
   A client with Storage Blob Data Contributor on the container and Storage Blob Delegator on the account.

   Credentials are read as for reports: [Keep reports in a bucket, step 3](/terragucci/guides/keep-reports-in-a-bucket/#3-give-the-job-an-identity-that-writes-only-reports).

3. Add the scheduled job.

**GitHub**
   `.github/workflows/estate.yml`:

   ```yaml
   name: estate
   on:
     schedule:
       - cron: "23 * * * *"
     workflow_dispatch: {}
   permissions:
     contents: read
     id-token: write
   jobs:
     estate:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: actions/setup-node@v4
           with:
             node-version: 24
         - uses: aws-actions/configure-aws-credentials@v4
           with:
             role-to-assume: arn:aws:iam::123456789012:role/terragucci-estate
             aws-region: us-east-1
         - run: npx --yes @intentius/terragucci estate
   ```
**GitLab**
   A job in `.gitlab-ci.yml`, and a schedule under Build, Pipeline schedules:

   ```yaml
   estate:
     image: node:24
     rules:
       - if: $CI_PIPELINE_SOURCE == "schedule"
     id_tokens:
       AWS_TOKEN:
         aud: sts.amazonaws.com
     variables:
       AWS_ROLE_ARN: arn:aws:iam::123456789012:role/terragucci-estate
       AWS_REGION: us-east-1
     script:
       - echo "$AWS_TOKEN" > "$CI_BUILDS_DIR/aws-token"
       - export AWS_WEB_IDENTITY_TOKEN_FILE="$CI_BUILDS_DIR/aws-token"
       - npx --yes @intentius/terragucci estate
   ```
**Forgejo**
   `.forgejo/workflows/estate.yml`, with `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` as repository secrets:

   ```yaml
   name: estate
   on:
     schedule:
       - cron: "23 * * * *"
     workflow_dispatch: {}
   jobs:
     estate:
       runs-on: docker
       container: node:24
       steps:
         - uses: actions/checkout@v4
         - run: npx --yes @intentius/terragucci estate
           env:
             AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
             AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
             AWS_REGION: us-east-1
   ```

   The tabs show AWS. On GCP or Azure, replace the AWS lines with the cloud's own:

   | Cloud | The job sets | On GitHub |
   |---|---|---|
   | GCP | `GOOGLE_APPLICATION_CREDENTIALS`, pointing at an `external_account` file for the service account of step 2, or a `service_account` key file | `google-github-actions/auth@v2` with `workload_identity_provider` and `service_account` writes the file and sets the variable |
   | Azure | `ARM_TENANT_ID`, `ARM_CLIENT_ID`, and the job's OIDC token (audience `api://AzureADTokenExchange`) in the file `ARM_OIDC_TOKEN_FILE_PATH` names; or the account key as `AZURE_STORAGE_KEY` | `permissions: id-token: write`, and a step that requests the token and writes the file |

4. Run it once. The log ends with the link:

   ```text
   estate: 3 projects, 1 wave waiting, 1 project drifted, 0 roots failed
     gitlab.example.com/platform/network: wave 2 waits, for 3h 0m
     github.com/acme/data: 2 roots drifted
   dora: 2.5 deployments per week, lead time 3h 10m, change failure rate 5%, time to restore 1h 20m
   wrote terragucci-estate/estate.json, terragucci-estate/estate.html, terragucci-estate/dora.json, terragucci-estate/history.json and terragucci-estate/history.html
   copied to s3://acme-terragucci/reports/estate.json, reports/estate.html, reports/dora.json, reports/history.json and reports/history.html
   link, until 2026-10-08T12:00:00.000Z:
   https://acme-terragucci.s3.us-east-1.amazonaws.com/reports/estate.html?X-Amz-Algorithm=AWS4-HMAC-SHA256&...
   ```

   The job fails (exit 1) when a project's index could not be read; the page still goes up and names that project.

5. Add a `terragucci audit` step before the estate step. It writes the audit trail (`audit.jsonl`, `audit.html`, `audit.json`) and the page links it. The approvers in the change history and the applies in the delivery metrics come from it. [The audit trail](/terragucci/reference/audit-trail/#write-it) lists what that step reads.

   ```yaml
   - run: npx --yes @intentius/terragucci audit
   - run: npx --yes @intentius/terragucci estate
   ```

6. Share the link in the drift issue or a chat channel.

   | Link lifetime | Set by |
   |---|---|
   | 24 hours | the default |
   | up to 168 hours | `--link-hours` |
   | shorter | the job's AWS role session, when that ends first; the log prints the real end |

The page's numbers need nothing else; its links to each run's report open where the bucket is served (`reports.url`, or your own front door).

## The resources

A `tf-apply` wave records the resources held by every root it applied or found nothing to apply in (address, type and provider, from the applied plan). The upload keeps each root's newest list in `inventory.json`.

| On the page | What it holds |
|---|---|
| a count at the top | resources across every project |
| per project | how many of each type |
| per root | each resource's address, type and provider, and the wave that recorded them |

No attribute value is ever recorded, sensitive or not. A root is listed from the first wave that applies it, and keeps its last list after you remove it from the repo.

## Change history

Each `tf-apply` wave also records what it did to each resource of the roots it applied, and the upload adds one row per resource to the project's `changes.json`. From these the estate job writes `history.html` and `history.json` beside the page, listing every resource address with each apply that changed it, oldest first. Each resource on the page links to its history.

| Action | Attributes named |
|---|---|
| `create`, `delete`, `import`, `move`, `forget` | none |
| `update`, `replace` | the top-level attributes whose value changed |

| Each apply shows | From |
|---|---|
| when, and what it did | the wave's plan |
| the attributes it changed, by name | the wave's plan |
| who approved the wave | the wave's apply entry in the [audit trail](/terragucci/reference/audit-trail/) |
| the commit, the wave, its report and the root's plan digest | the wave's report |

Without the audit trail (step 5) the history lists every apply but names nobody. A wave no gate held has no approver.

For a [choudoufu](/terragucci/concepts/glossary/#choudoufu) estate, each wave also lists the past versions of each record it changed with `choudoufu live-history`: version id, time, and whether it is current or deleted, never a value. The page shows the count beside the resource. A `local` or `kubernetes` record store keeps none, and the page says so. Listing takes `s3:ListBucketVersions` on the record store bucket; when the root's identity lacks it, the history shows choudoufu's error.

## State versions

A `tf-apply` wave records the version id of each root's state from the bucket's versioning. The page lists them per root, newest first. When the backend keeps no history (a bucket with versioning off, or a `local`, `pg`, `kubernetes`, `consul` or plain `http` backend), it says versions are off. When the backend may keep versions terragucci does not read, such as `remote`, it says versions not read, and why. [Find the state version an apply left](/terragucci/guides/find-a-state-version/) sets this up and says how to go back to a version.

## Cross-state edges

A root that reads another root's state (`terraform_remote_state` or a Terragrunt `dependency` block) is marked stale when the producer applied a change after the consumer's last plan. [Track the roots that read other roots' state](/terragucci/guides/track-cross-state-edges/) covers the edge sources and fixing a stale one.

## Delivery metrics

For each project and the estate, the Delivery section shows the four DORA metrics week by week over the newest eight weeks. The same numbers go to `dora.json` beside the page.

| Metric | What the page counts |
|---|---|
| Deployment frequency | applied waves per week |
| Lead time | the median time from a change's first plan to its wave applied, and that time before the gate, at the gate and after the approval |
| Change failure rate | failed applies, plus applied waves whose roots drifted within 7 days, over all applies; a refused wave does not count |
| Time to restore | the median time from a failed apply to the next apply of those roots, and from drift found to the next drift check that found none |

The applies come from the audit trail (step 5). With an OTLP endpoint set, the job also sends the four as gauges for the Estate dashboard.

## A resource graph beside the page

The estate page counts per project. To see which resources in which roots drifted or will change, the job can publish a [behold](https://intentius.io/behold/using/terragucci/) view next to it. It is optional, and terragucci does not run or need it. To look at one repo on your machine instead, see [See your estate in behold](/terragucci/guides/see-your-estate-in-behold/).

Add one step after the estate step, in a repo whose roots the view should draw:

```yaml
- run: >-
    npx --yes -p @intentius/behold@0.25.0 -p @intentius/chant-lexicon-terraform@^0.121.0 -p @cdktn/hcl2json@^0.24.0
    behold export . --terragucci s3://acme-terragucci/reports --no-source
    --publish s3://acme-terragucci/reports/views/behold
```

| The view shows | From |
|---|---|
| every root of the checkout and the resources it declares | the checkout |
| on each resource, what the newest drift check and plan found, and when | each root's newest `tf-drift` and `tf-plan` report |
| each waiting wave, with the `terragucci approve` line to run | `estate.json` |
| the counts, as the estate page shows them, with a link to it | `estate.json` |

Each run publishes the view for the checkout's commit under `reports/views/behold/<commit>/` and keeps the 30 newest (`--keep <n>` changes it). `reports/views/behold/index.html` opens the newest, and a picker in the view opens an older commit.

It writes only under `reports/views/behold/`, which terragucci never writes, with the job's credentials. Add `s3:GetObject` on `reports/*/report.json`, and `s3:PutObject`, `s3:GetObject` and `s3:DeleteObject` on `reports/views/behold/*`, to the policy of step 2. A commit past the newest 30 is deleted. Its links open each run's report through the same presigned link or front door as the page. `--no-source` leaves each root's HCL out of the view.

Give the step `continue-on-error: true` on GitHub and Forgejo, or `allow_failure: true` on GitLab: a view that cannot be built leaves the estate page as it is.

## Next

- [CLI commands](/terragucci/reference/cli/#estate) lists the flags.
- [The audit trail](/terragucci/reference/audit-trail/) describes every entry of `audit.jsonl`.
- [Delivery metrics](/terragucci/reference/delivery-metrics/) defines each DORA metric and the fields of `dora.json`.
- [Report JSON schema](/terragucci/reference/report-schema/#the-index-and-the-estate-page) describes `estate.json`, the index rows, `inventory.json`, `changes.json` and `history.json`.

---

# See your estate in behold

Source: https://intentius.io/terragucci/guides/see-your-estate-in-behold/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/see-your-estate-in-behold/.
In this repo, start behold with the command the page gives, reading the reports bucket this repo's terragucci.yml names, and tell me which resources are marked and how old each mark is. Do not create or print credentials.
Read only, and never deploy from behold. Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

The [estate page](/terragucci/guides/see-every-project/) counts per project. [behold](https://intentius.io/behold/using/terragucci/) draws one repo's roots and resources as a graph and marks each resource with what your runs last found about it. It runs on your machine against the checkout and the reports bucket. Nothing is written, and the pipeline never needs it.

## Result

```bash
npx --yes -p @intentius/behold@0.25.0 -p @intentius/chant-lexicon-terraform@^0.121.0 -p @cdktn/hcl2json@^0.24.0 \
  behold serve . --terragucci s3://acme-terragucci/reports
```

Use the bucket and prefix from your `terragucci.yml`, then open `http://127.0.0.1:4600`. Each root is a box of its resources. A resource a run flagged carries a mark with the time that run finished, and the **Terragucci** tab lists every root with its newest drift check, plan and apply wave.

## Marks

| Mark | Means | From |
|---|---|---|
| ⚠ drift | the newest drift check found the resource changed or deleted outside Terraform, or existing outside the state | the root's newest `tf-drift` report |
| ~ plan | the newest plan that holds the root would change the resource, with its pull request | the root's newest `tf-plan` report |
| ⏸ wave | a wave waiting for an approval would change the resource | the waiting `tf-apply` wave's report |

Each card's corner says how old its newest mark is. Click a card to list its marks with the finish time and report of each run. A mark is what a run saw when it ran, and nothing on the page is a live read. A card with no mark is one no report names; it may still differ from the cloud. A root no run planned says "no report".

When the bucket holds `estate.json`, behold shows the estate page's own counts.

## Waiting waves

A waiting wave lists its roots and what it destroys or replaces. It says how long it has waited and gives the line to approve it:

```bash
npx terragucci approve wave-2 --plan jcs1-sha256:2e0f...
```

behold has no approve button. Run the line in your shell, which records the approval on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) against that plan digest, as in [Approve a wave](/terragucci/guides/approve-a-wave/). In a repo with a `terragucci.yml`, behold refuses to deploy or approve or start a run.

## Prerequisites

| You need | Why |
|---|---|
| Node.js 20 or later | `npx` runs terragucci and behold |
| a checkout of the repo | behold draws the roots from its Terraform files |
| [reports in a bucket](/terragucci/guides/keep-reports-in-a-bucket/) | the marks come from the reports there |
| read access to the bucket, or a copy of the prefix | behold reads the reports with your own credentials |

## Steps

1. Give your shell read access to the reports. behold reads an S3 prefix with your AWS profile. A read-only identity needs `s3:GetObject` on these keys:

   ```text
   <prefix>/*index.json
   <prefix>/*/report.json
   <prefix>/estate.json
   ```

   For a GCS or Azure bucket, set `reports.url`, or copy the prefix to a directory with `gcloud storage rsync` or `azcopy`.

2. From the repo's root, run the command under [Result](#result). To read a copy instead of the bucket, pass the directory:

   ```bash
   aws s3 sync s3://acme-terragucci/reports ./reports
   npx --yes -p @intentius/behold@0.25.0 -p @intentius/chant-lexicon-terraform@^0.121.0 -p @cdktn/hcl2json@^0.24.0 \
     behold serve . --terragucci ./reports
   ```

3. If the bucket holds several repos and none matches this checkout's git remote, add `--terragucci-project github.com/acme/infra`.

4. Stop it with Ctrl-C. behold binds `127.0.0.1` only.

## Limits

- behold 0.25.0 reads repos whose [`chant.workspace.json`](/terragucci/concepts/glossary/#chantworkspacejson) asks for `minReader` 0.121.0 or older; `terragucci init` writes 0.102.0. It refuses a repo that asks for a newer reader.
- A malformed `index.json`, `report.json` or `estate.json` is refused with what to fix, rather than drawn.
- A [control repo](/terragucci/concepts/control-repo/) has no roots of its own, so behold draws nothing there. Serve each project's repo.

## Share a view

For a link the team can open without running anything, the estate job can publish a static view next to the estate page: see [A resource graph beside the page](/terragucci/guides/see-every-project/#a-resource-graph-beside-the-page). behold is never hosted as a shared server.

## Next

- [Approve a wave](/terragucci/guides/approve-a-wave/) runs the approve line.
- [The reports bucket](/terragucci/reference/reports-bucket/) lists the files behold reads.

---

# Track the roots that read other roots' state

Source: https://intentius.io/terragucci/guides/track-cross-state-edges/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/track-cross-state-edges/.
List the terraform_remote_state blocks in this repo's roots and the root whose state each reads, from the backend blocks, and tell me which reads terragucci cannot match to a root.
Read only. Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

A Cross-state edges section on the [estate page](/terragucci/guides/see-every-project/). It lists each root that reads another root's state, by producer. Beside each edge are the consumer's last plan and the producer's last apply that changed it, and a status.

| Status | Means |
|---|---|
| `stale` | the producer applied a change after the consumer's last plan, so that plan read outputs that have changed since |
| `current` | the consumer's last plan is newer than the producer's last change |
| `unknown` | no plan of the consumer, or no apply of the producer that changed it, is recorded yet |

A consumer goes stale when a change reaches the producer and not the consumer: its wave applies the producer, and nothing plans the consumer again.

## Edge sources

| A root reads another through | terragucci reads |
|---|---|
| a `terraform_remote_state` block whose config names the state another root's backend block names | the code of both roots, as it orders the apply waves |
| a Terragrunt unit's `dependency` or `dependencies` block | the unit's `terragrunt.hcl` |

## State addresses

A read matches a root when both name the same address:

| Backend | Address |
|---|---|
| `s3`, `gcs`, `azurerm` | `bucket` and `key` (`prefix` for gcs) |
| `local` | `path`, resolved against the root's directory; a root with no backend block keeps `terraform.tfstate` there |
| `pg` | the host and database in `conn_str`, `schema_name` and `table_name` |
| `http` | `address`, such as GitLab's `.../projects/<id>/terraform/state/<name>` |
| `consul` | `address` and `path` |
| `kubernetes` | `namespace` and `secret_suffix` |
| `remote`, or a `cloud` block | `hostname`, `organization` and the workspace `name` |

Credentials in `conn_str` or `address` are dropped from the address.

An address that is not plain strings in the code can't be matched. This covers an expression such as `var.env`, a value the backend takes from the environment (`PG_CONN_STR`, `TF_HTTP_ADDRESS`, `CONSUL_HTTP_ADDR`, `KUBE_NAMESPACE`, `TF_CLOUD_ORGANIZATION`) or from a `-backend-config` file, and a workspace picked by tags or prefix. Nothing orders that read, so terragucci names it:

- `terragucci config check` warns for each such read, and for each root whose own state has no address when any root reads state.
- The report lists the read under `roots[].unknown_reads` and the root under `roots[].unaddressed`.
- The plan log and `report.html` name both.

Write the address in the block to give the read its edge.

A report lists a root's `terraform_remote_state` reads as `roots[].reads` and a unit's dependencies as `roots[].dependencies`. Every upload keeps them in the project's `edges.json` beside each root's newest plan run and newest apply wave that changed it. The reads follow the newest plan or apply of the default branch. A pull request's plan or a drift check moves the consumer's last plan forward but never changes its reads. Nothing reads a state or an output's value.

## Steps

1. Keep [reports in a bucket](/terragucci/guides/keep-reports-in-a-bucket/). From then on, each run's upload writes `edges.json`.

2. Run `terragucci estate` (its scheduled job also runs it) and open the link it prints.

3. For a stale edge, plan the consumer again: `/terragucci plan <root>` on a pull request, or a drift check of the default branch. When the plan changes something, the producer's new outputs reach the consumer through a change you review.

## Next

- [Report JSON schema](/terragucci/reference/report-schema/#cross-state-edges) for `edges.json` and `projects[].edges`.
- [Plan grouping](/terragucci/concepts/why-plans-are-grouped/) for how remote state orders the waves.

---

# Use Atmos

Source: https://intentius.io/terragucci/guides/use-atmos/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/use-atmos/.
Run `npx terragucci init --dry-run --json`, list the instances and waves it found,
tell me about any instance it refused and why, and open a pull request with the pipeline.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

A pipeline whose roots are your [Atmos](https://atmos.tools) component instances, one per stack and component, applied a dependency layer at a time behind the same gate as plain roots.

## Prerequisites

| You need | Why |
|---|---|
| An `atmos.yaml` at the repo root | `init` detects Atmos from it |
| Atmos on the path, or `TERRAGUCCI_ATMOS` naming it | `init` runs `atmos describe stacks` |
| A remote backend for each instance, such as `s3` | each job starts from a fresh checkout |
| terragucci installed ([Get your first plan note](/terragucci/getting-started/)) | `init` writes the pipeline |

## Steps

1. Run init.

   ```bash
   npx terragucci init --dry-run
   ```

   It prints the instances and how many waves they make:

   ```text
   found Atmos (atmos.yaml): 4 instances in 2 waves from atmos describe stacks, ...
   ```

2. Write the pipeline.

   ```bash
   npx terragucci init
   ```

   Commit it and open a pull request.

## Instances

| What | How |
|---|---|
| A root | one instance, named `<stack>/<component>`, such as `prod/vpc` |
| Which instances | every Terraform instance `atmos describe stacks` lists, less abstract ones (`metadata.type: abstract`) and disabled ones (`metadata.enabled: false`) |
| `roots` and `synth` | refused: the stacks decide the roots |
| An instance that sets `env` or `generate` | refused; move the setting into the component's Terraform, or disable the instance |

## Refused settings

`terragucci atmos write` makes each instance's directory as a copy, so `config check` and `init` refuse settings that would edit it:

| Setting | Instead |
|---|---|
| `drift` with the drift pull request, the default `respond.drift` | `respond.drift: attribute` or `off`; a live value belongs in the stack's vars or the component |
| `rollouts` | move the pin in the component, which every instance of it shares |
| `generate` | the stack's `backend` and `providers` settings |
| `ephemeral` | none |

## Waves

| What | How |
|---|---|
| Order | `dependencies.components`, and `settings.depends_on`; an entry with no `stack` means the instance's own stack |
| A read with `!terraform.state` or `!terraform.output` | puts the instance after the one it reads |
| Each wave | one dependency layer, in its own apply job behind its own gate |
| A dependency on a disabled instance | holds nothing back |
| A dependency no stack deploys, or a cycle | `init` stops and names it |
| `waves.canary` | the canary instances' layers go first |

## Jobs

Before reading the roots, every job installs Atmos 1.230.1 (checked against the release's `SHA256SUMS`) and runs `terragucci atmos write`. For another release, set it in `terragucci.yml` and rerun `init`:

```yaml
atmos:
  version: 1.230.0
```

The check job runs `atmos validate stacks` first, so a manifest Atmos refuses fails the check with Atmos's own error.

| `terragucci atmos write` | |
|---|---|
| Reads | `atmos describe stacks`, with `!terraform.state`, `!terraform.output` and `!store` left unevaluated |
| Writes | the component's Terraform to `<stack>/<component>`, with the varfile, backend and provider override Atmos generates for that instance |
| Local module sources | a `../` source outside the component is rewritten to reach the same directory from the copy |
| A directory of your repo at `<stack>/<component>` | refused |

These directories are made in the job. If you run `terragucci atmos write` yourself, add them to `.gitignore`.

## Workspaces

Each instance plans and applies in the Terraform workspace Atmos names for it, never `default`. With an `s3` backend its state is at `<workspace_key_prefix>/<workspace>/<key>`, as Atmos keeps it.

`terragucci plan`, `unlock-state`, `state export` and a state migration run each instance in its workspace too.

## Tips

The tip pull requests pin providers and add lock files in the components, which git holds, and name instances in a canary wave.

## Pull requests

A pull request plans the instances whose written files differ from the base's, and every instance that depends on one of them. The plan job also writes the instances at the base and compares the two without a cloud credential.

| A pull request that changes | Plans |
|---|---|
| `prod/vpc`'s vars | `prod/vpc`, then `prod/app`, which depends on it |
| a component's Terraform | every instance of that component, and their dependents |
| nothing an instance is written from | nothing |

## Approval

A wave applies the plans whose digest was approved, as plain roots do. If the stacks change after the approval, the wave plans again and applies nothing. It names the instances that moved; approve the new plans to apply them.

## Reads of another instance

A var set with `!terraform.state` or `!terraform.output` reads another instance's outputs:

```yaml
components:
  terraform:
    app:
      vars:
        vpc_cidr: !terraform.state vpc .cidr
```

`atmos describe stacks` runs before the job has a cloud credential, so the job reads the value itself afterwards from the state in the upstream's own workspace. While the upstream has no state, the instance is held back rather than planned on a stand-in; the plan note names the instance it waits for.

| Form | Read |
|---|---|
| `!terraform.state <component> <output>` | the output of the instance in the same stack |
| `!terraform.state <component> <stack> <output>` | the output of the instance in another stack |
| An output as `.name` or `.name.key` | that output, or a key inside it |
| `!terraform.output` | the same as `!terraform.state` |
| `!store`, a read inside a map or a list, or a yq expression | refused; output the value from an instance and read it whole |

## Roles by stack

An instance's root is `<stack>/<component>`, so `oidc.roles` globs give each stack its roles:

```yaml
oidc:
  roles:
    "dev/*": { plan: arn:aws:iam::111:role/dev-plan, apply: arn:aws:iam::111:role/dev-apply }
    "prod/*": { plan: arn:aws:iam::222:role/prod-plan, apply: arn:aws:iam::222:role/prod-apply }
```

`terragucci config check` lists each role with its stack's instances and their state keys, and warns when an instance reads another stack's state. A read uses the upstream's role.

## Next

- [Approve a waiting wave](/terragucci/guides/approve-a-wave/)
- [Use Terragrunt](/terragucci/guides/use-terragrunt/), the same model for units

---

# Use Terramate

Source: https://intentius.io/terragucci/guides/use-terramate/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/use-terramate/.
Run `npx terragucci init --dry-run --json`, list the stacks and waves it found,
tell me about anything it refused and why, and open a pull request with the pipeline.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

A pipeline whose roots are your [Terramate](https://terramate.io) stacks, applied in the order Terramate gives them, a layer at a time behind the same gate as plain roots.

## Prerequisites

| You need | Why |
|---|---|
| `terramate.tm.hcl` at the repo root, or a `stack.tm.hcl` below it | `init` detects Terramate from it |
| Terramate on the path, or `TERRAGUCCI_TERRAMATE` naming it | `init` runs `terramate list` and `terramate experimental run-graph` |
| Generated code committed and up to date | the jobs plan what git holds |
| A remote backend for each stack, such as `s3` | each job starts from a fresh checkout |
| terragucci installed ([Get your first plan note](/terragucci/getting-started/)) | `init` writes the pipeline |

## Steps

1. Run init.

   ```bash
   npx terragucci init --dry-run
   ```

   It prints the stacks and how many waves they make:

   ```text
   found Terramate (terramate.tm.hcl): 3 stacks in 2 waves from terramate list and the stacks' order, ...
   ```

2. Write the pipeline.

   ```bash
   npx terragucci init
   ```

   Commit it and open a pull request.

## Stacks

| What | How |
|---|---|
| A root | a stack `terramate list` names that holds Terraform, by its directory, such as `stacks/app` |
| A stack with no Terraform | not a root; the order through it is kept |
| Leaving a stack out | a `.tmskip` file in its directory, as Terramate reads it |
| `roots` and `synth` | refused: Terramate decides the stacks |

## Waves

```hcl
stack {
  id    = "app"
  after = ["tag:net"]
}
```

| What | How |
|---|---|
| Order | `after` and `before`, with stack paths, directories and `tag:` filters, as `terramate experimental run-graph` resolves them |
| Nesting | a parent stack runs before the stacks under it |
| An `input` block | puts the stack after the one it reads |
| `terraform_remote_state` between stacks | puts the reader after the stack it reads, as for plain roots |
| Each wave | one layer, in its own apply job behind its own gate |
| A path in `after` or `before` that names no stack, or a cycle | `init` stops and names it; Terramate only warns about the path |
| `waves.canary` | the canary stacks' layers go first |

## Jobs

Every job installs Terramate 0.17.3, checked against the release's `checksums.txt`, then runs `terragucci terramate generate` before it reads the stacks:

| Step | |
|---|---|
| `terramate generate --detailed-exit-code` | when it would change a file, the job fails, naming the file; run `terramate generate` and commit, as `terramate run` asks too |
| Edges | each stack's order and inputs, written to `.terragucci-terramate.json` beside it in the job |

## Pull requests

A pull request plans the stacks its diff touches, and every stack that runs after one of them.

| A pull request that changes | Plans |
|---|---|
| `stacks/network` | `stacks/network`, then `stacks/app`, whose `after = ["tag:net"]` matches it |
| a global in `terramate.tm.hcl`, with the generated code | every stack whose generated files changed, and the stacks after them |
| a global, without the generated code | nothing: the check fails on the stale code |

## Outputs sharing

An `input` block reads another stack's output:

```hcl
input "net_name" {
  backend       = "default"
  from_stack_id = "network"
  value         = outputs.name.value
}
```

The job reads the upstream's outputs from its state, once it has a cloud credential, and fills the variable Terramate generated. While the upstream has no state, the stack is held back rather than planned on its `mock`, and the plan note says which stack it waits for. The `sharing_backend` command is not run; the stack's own binary reads the state.

| `value` | Read |
|---|---|
| `outputs.<name>.value` | that output |
| `outputs.<name>.value.key` or `["key"]` | a key inside it |
| Anything else, such as a function call | refused; read the upstream with a `terraform_remote_state` data source |
| A `from_stack_id` no stack has | refused |

## Not read

Terramate's `watch` files, scripts, `wants` and `wanted_by`, and Terramate Cloud. terragucci's own affected selection and [steps](/terragucci/guides/run-steps/) run instead. A drift pull request, `rollouts` and `generate` are refused, since their edits would land in code `terramate generate` owns; `respond.drift: attribute` names who changed each value in the drift issue.

## Next

- [Approve a waiting wave](/terragucci/guides/approve-a-wave/)
- [Use Atmos](/terragucci/guides/use-atmos/), the same model for component instances

---

# Watch a choudoufu wave apply

Source: https://intentius.io/terragucci/guides/watch-a-choudoufu-wave/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/watch-a-choudoufu-wave/.
For the commit I name, read run.json under my reports prefix and tell me, for each wave applying, how many resources are done, in flight and waiting, and which ones.
Read only: write nothing to the bucket.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

While a wave applies, each resource its plans change shows as done, in flight or waiting. After it applies, each changed resource lists its record's past versions.

## Prerequisites

| You need | Why |
|---|---|
| [`binary: choudoufu`](/terragucci/guides/use-a-binary/#choudoufu) and roots under live resource markers with a record store | progress is read from the estate's records |
| [Reports in a bucket](/terragucci/guides/keep-reports-in-a-bucket/) | the run view and the estate page live there; without one, only the job's log and `progress.json` show it |
| The [estate page](/terragucci/guides/see-every-project/), with its `terragucci audit` step | the resource history and the counts across projects |

## Progress

The wave reads its estates' records, not the apply's output. A resource is done once its record is written or removed, which choudoufu does as each resource's apply returns. It is in flight once every resource it depends on is done, and waiting before that.

1. Push a change. When a wave's gate lets it through and its roots start applying, the job's log names what it follows, then prints a line each time the records move:

   ```text
   wave 1 of 2: following 4 resources in the records of app
   wave 1 of 2: progress 2 of 4 done, 1 in flight, 1 waiting
   ```

2. Open the run view, `<prefix>/<project>/runs/<commit>/run.html` in the bucket. The applying wave's column lists each resource with its state, and the page reloads every 15 seconds while a wave applies. `run.json` carries the same list in `waves[].progress`.

3. Or read `terragucci-report/progress.json` in the job's report, written each time the list changes.

4. On the estate page, each project with a wave applying shows `wave <n> applying` with its counts, linked to the run view, as of the estate job's last run.

| Setting | Effect |
|---|---|
| `TG_PROGRESS_SECONDS` | seconds between reads of the records; 5 by default |

A store terragucci cannot read, such as a `kubernetes` record store, gives no records: the job logs it once, and that root's resources show done when its apply returns. Once a root's apply fails, what it did not finish shows as not applied.

## Record history

After it applies, a `tf-apply` wave runs `choudoufu live-history` in each choudoufu root for each resource the apply changed, under the identity it reads that root's records with. It keeps each version's id, its time, and whether it is current or deleted, never a value.

1. Read the wave's log, one line per root:

   ```text
   app: record versions: aws_sqs_queue.jobs 3 versions; terraform_data.seed 1 version
   ```

2. On the estate page, each resource of the estate shows its version count beside it, linked to its history.

3. The history page, `history.html`, lists each apply that changed the resource with who approved it, and below it the record's versions, newest first. Reading one version's contents takes `aws s3api get-object --version-id` with your own identity.

| The store | The history says |
|---|---|
| `s3` | each version the bucket keeps; listing takes `s3:ListBucketVersions` on the record store bucket |
| `local` or `kubernetes` | no past versions kept: the store replaces a record in place |
| the identity cannot list them | versions not listed, with choudoufu's error; the wave still applies |

`roots[].applied_changes[].record_versions` in the wave's report holds the same ([Report JSON schema](/terragucci/reference/report-schema/)).

## Next

- [Waves and approvals](/terragucci/concepts/waves-and-approvals/#the-run-view) has the run view's other parts.
- [Locking and staleness](/terragucci/concepts/locking-and-staleness/#with-choudoufu) explains why choudoufu takes no state lock.

---

# Write a policy

Source: https://intentius.io/terragucci/guides/write-a-policy/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/guides/write-a-policy/.
Write a Rego rule under the policy directory that denies the case I name, with a test, run `conftest verify --policy policy`,
add the `policy:` key to terragucci.yml, run `npx terragucci config check --json` and `npx terragucci init`, and open a pull request.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

## Result

A rule in your repo that fails `tf-plan` for each root whose plan it denies, names the denial in the plan note, and keeps a denied wave from applying.

## Prerequisites

| You need | Why |
|---|---|
| The pipeline from [Get your first plan note](/terragucci/getting-started/) | the plan, check and apply jobs run the policy |
| [conftest](https://www.conftest.dev/) on your machine, to run the tests before you push | the jobs download the engine themselves |

## Steps

1. Write the rule in `policy/`. It reads one root's plan, `show -json`, as `input`:

   ```rego
   # policy/sqs.rego
   package main

   import rego.v1

   deny_long_retention contains msg if {
     some rc in input.resource_changes
     rc.type == "aws_sqs_queue"
     rc.change.after.message_retention_seconds > 345600
     msg := sprintf("%s keeps messages longer than four days", [rc.address])
   }
   ```

   `deny`, `violation` and any `deny_<name>` fail the root; `warn` only warns. [Policy](/terragucci/reference/policy/#counted-rules) lists the rules and the [input](/terragucci/reference/policy/#rego-input).

2. Test it beside the rule and run the tests:

   ```rego
   # policy/sqs_test.rego
   package main

   import rego.v1

   test_denies_a_week if {
     count(deny_long_retention) == 1 with input as {"resource_changes": [{"address": "aws_sqs_queue.jobs", "type": "aws_sqs_queue", "change": {"after": {"message_retention_seconds": 604800}}}]}
   }
   ```

   ```bash
   conftest verify --policy policy
   ```

   `tf-check` runs the same tests on the default branch's policy and fails on a failing one.

3. Turn policy on in `terragucci.yml`:

   ```yaml
   policy:
     engine: conftest
     path: policy
   ```

4. Check the file and write the pipeline again:

   ```bash
   npx terragucci config check
   npx terragucci init
   ```

5. Open a pull request with the rule, its test, the key and the pipeline, and merge it.

   A pull request is checked against the `policy` key and directory on its base branch. Until they merge, a change that edits or deletes the policy cannot loosen it.

6. Open a pull request with a change the rule denies. The plan job fails, and the note names the root and the denial:

   The denial and its rule id, such as `main.deny_long_retention`, are in `roots[].policy` of the report. A sensitive value in a message is redacted before it reaches the note or the log.

7. Clear the denial. Change the code until the rule passes, or change the rule in a pull request your reviewers approve and merge.

## Override a denial

When a denied plan has to go out, a person you list can let that one plan through `tf-apply`. Name them at base:

```yaml
policy:
  engine: conftest
  path: policy
  override: [github:alice, github:bob]
```

The wave records the denial and prints a `terragucci override` command for the root. [Override a policy denial](/terragucci/guides/approvals-runbook/#override-a-policy-denial) has the steps, and [Overriding a denial](/terragucci/reference/policy/#overriding-a-denial) what an override binds. `tf-plan` still fails the root; the override counts only in the apply wave, and only for that plan and those rules.

## Next

- [Policy](/terragucci/reference/policy/) has a shared policy source, `opa`, HCP Terraform policy sets, cost and review input.
- [The audit trail](/terragucci/reference/audit-trail/) keeps every override with its reason.

---

# The launch party

Source: https://intentius.io/terragucci/launch-party/

terragucci launched at a party in Rome, Italy, where its creator vibe coded it on stage in one shot.

<video
	class="tg-launch-video"
	controls
	playsinline
	preload="metadata"
	poster="/terragucci/media/poster.jpg"
	aria-label="On stage in Rome, with the crowd holding up diamond tacos"
>
	<source src="/terragucci/media/launch-party.mp4" type="video/mp4" />
	<a href="/terragucci/media/launch-party.mp4">Download the launch party video</a> (MP4, 13 MB).
</video>

---

# The audit trail

Source: https://intentius.io/terragucci/reference/audit-trail/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/reference/audit-trail/.
Download audit.jsonl from the top of my reports prefix with a read-only identity, run the queries
under "Query the record", and tell me, per project, every approval with its approver, plan digest
and time, every policy override with its reason, every refused wave and every failed apply in the
last 30 days, each with its evidence link.
Read only: do not run `terragucci audit` without `--check`, and write nothing to the bucket.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

`terragucci audit` writes the record as JSON lines in your reports bucket. It reads the approval ledger on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) in each repo and the wave reports in the bucket; no terragucci server or account holds a copy.

## Write it

1. Run it where the [estate page](/terragucci/guides/see-every-project/) job runs, before `terragucci estate`:

   ```bash
   npx --yes @intentius/terragucci audit
   npx --yes @intentius/terragucci estate
   ```

   | Run from | Projects | Ledger read from | Reports read from | Record written to |
   |---|---|---|---|---|
   | a [control repo](/terragucci/concepts/control-repo/) | its `projects:` | each project's repo: its `url`, else `https://<key>`, with the forge token when the job has one | each project's `reports` | `defaults.reports` |
   | one repo | the checkout's own | `origin` | the repo's `reports` | the same bucket |

2. Give the job what it reads. On top of the estate job's identity:

   | Reads | Why |
   |---|---|
   | `chant/lifecycle` of each project, with its history | every approval, override and revocation |
   | `<prefix>/<project>/**/tf-apply-wave-*/report.json` | every apply and its result, every refused wave |
   | `<prefix>/audit.jsonl`, and writes it, `audit.html` and `audit.json` | the record, its page and its summary |

   The forge token is the project's `token_env`, else `GITHUB_TOKEN`, `GITLAB_TOKEN` or `FORGEJO_TOKEN`, with read access to the repo.

3. Read the log:

   ```text
   audit: 214 entries, 3 added
     2026-10-08T09:12:44.000Z github.com/acme/network approval wave-2 by dana sha256:4be1...: unsigned
     2026-10-08T09:20:03.000Z github.com/acme/network apply wave-2 by dana sha256:4be1...: applied
     2026-10-08T10:01:17.000Z gitlab.example.com/platform/data refused wave-1 by lee sha256:9c07...: changed-after-approval
   wrote terragucci-audit/audit.jsonl, terragucci-audit/audit.html, terragucci-audit/audit.json
   copied to s3://acme-terragucci/reports/audit.jsonl, reports/audit.html, reports/audit.json
   link, until 2026-10-09T10:05:00.000Z:
   https://acme-terragucci.s3.us-east-1.amazonaws.com/reports/audit.html?X-Amz-Algorithm=AWS4-HMAC-SHA256&...
   ```

   A project whose ledger or index cannot be read makes the job exit 1 and is named on the page. The entries it could read still land.

The estate page links `audit.html` once `audit.json` is beside it, and its [resource history](/terragucci/guides/see-every-project/#change-history) names each apply's approver from the record. Flags are on [CLI commands](/terragucci/reference/cli/#audit).

## Storage

| Object | What it is |
|---|---|
| `<prefix>/audit.jsonl` | the record: one entry per line, oldest first within each run's additions |
| `<prefix>/audit.html` | the page: counts by kind, each project's ledger state, the newest 1000 entries with their evidence links |
| `<prefix>/audit.json` | the summary, `terragucci.audit-summary/v1`: how many entries, how many the last run added, counts by kind, and each project's ledger state |

## Entry fields

Every line is `terragucci.audit/v1` (JSON Schema in the package as `dist/audit.schema.json`), and holds these fields in this order:

| Field | What it holds |
|---|---|
| `schema` | `terragucci.audit/v1`; a new field never changes an existing one |
| `id` | `sha256:` over where the entry came from: the ledger line, or the report's path and finish time |
| `kind` | what happened; see the next table |
| `project` | `<host>/<path>` of the repo |
| `at` | when: the ledger line's `timestamp`, the commit that removed a line, or the run's finish |
| `who` | the approver, the overrider, whoever removed the line, or for an apply the approver it applied under; `null` when nobody did |
| `what` | the gate: `wave-<k>`, a migration's name, or for an override or a lock's release the root |
| `digest` | the plan digest: the wave's set digest, or the digest an override binds; `null` when a root failed to plan |
| `result` | the outcome; see the next table |
| `evidence` | `source` (`ledger` or `report`); for the ledger `branch`, `path` and `commit`; for a report `bucket`, `key` and `job_url`; `url`, the commit's page or the run's `report.html`, when it is known |
| `detail` | what else the source says, by kind |

## Kinds and results

| `kind` | From | `result` | `detail` |
|---|---|---|---|
| `approval-requested` | a pending line in `_gates/tf-apply.jsonl`, `_gates/tf-migrate.jsonl` for a migration, `_gates/tf-unlock.jsonl` for a state lock's release, `_gates/tf-state-export.jsonl` for a [state export](/terragucci/guides/export-a-state-version/), or `_gates/tf-ephemeral.jsonl` for a pull request's [ephemeral copy](/terragucci/guides/ephemeral-environments/) | `waiting` | `expires`, `run_id`, `description`, `roots` |
| `approval` | an approval line in `_gates/tf-apply.jsonl`, `_gates/tf-migrate.jsonl`, `_gates/tf-unlock.jsonl`, `_gates/tf-state-export.jsonl` or `_gates/tf-ephemeral.jsonl` | `unsigned`, `sealed` or `review` | `signer` (sealed), `via`, `pr`, `head`, `reviewers` (review), `relayed_by`, `committed_by` |
| `approval-revoked` | an approval line a commit removed | `revoked` | `approved_by`, `approved_at`, `signer` (sealed) |
| `override-requested` | a denial a wave recorded in `_gates/policy-override.jsonl` | `denied` | `expires`, `run_id`, `description`, `rules`, `plan_digest` |
| `override` | an override line in `_gates/policy-override.jsonl` | `unsigned` or `sealed` | `reason`, `rules`, `plan_digest`, `signer`, `relayed_by`, `committed_by` |
| `override-revoked` | an override line a commit removed | `revoked` | `approved_by`, `approved_at`, `signer` (sealed) |
| `apply` | a `tf-apply` wave report | `applied`, `failed` or `waiting` | `wave`, `commit`, `roots`, `gate`, `approval` (the id of the approval entry it applied under), `changes`, `failed`, `overrides`, `pull_request`, `state_versions` (each root's state `location`, `version_id` and `versioning`) |
| `migration` | a line in `_gates/tf-migrate/done.jsonl`, written when a [state migration](/terragucci/reference/migration-files/) wrote its states | `applied` or `failed` | `roots` (each root's `location` and state version `before` and `after`, and both digests), `file_digest`, `error`, `commit`, `run_id` |
| `unlock` | a line in `_gates/tf-unlock/done.jsonl`, written when [`terragucci unlock-state`](/terragucci/reference/cli/#unlock-state) released a state lock; `who` is who released it and `what` the root | `released` | `location`, `lock_id`, `operation`, `locked_by`, `locked_at` (the lock as the binary wrote it), `approved_by`, `approved_at`, `commit` |
| `state-export` | a line in `_gates/tf-state-export/done.jsonl`, written by [`terragucci state export`](/terragucci/reference/cli/#state-export) before it writes the file; `who` is the person who exported, `what` the root | `exported` | `location`, `version_id`, `approved_by`, `approved_at`, `content_digest` (the digest of the bytes written, never the bytes) |
| `ephemeral-apply` | a line in `_gates/tf-ephemeral/done.jsonl`, written when a pull request's [ephemeral copy](/terragucci/guides/ephemeral-environments/) applied; `who` is the forge's actor for the job, `what` the gate `pr-<n>`, `digest` the copy's plans | `applied` or `failed` | `pull_request`, `suffix`, `roots` (each root's state `location` and `result`), `expires`, `approved_by`, `commit`, `run_id` |
| `ephemeral-destroy` | a line in `_gates/tf-ephemeral/done.jsonl`, written when a copy was destroyed; `digest` is the destroy plans' | `destroyed` or `failed` | `pull_request`, `suffix`, `roots`, `reason` (`closed` or `expired`), `commit` (the code the destroy ran), `run_id` |
| `refused` | a `tf-apply` wave report's `waves[].refused` | `changed-after-approval`, `changed-after-review`, `changed-after-override`, `denied-by-policy`, `held-by-another-apply` or `superseded-by-a-newer-push` | `wave`, `commit`, `roots`, `pull_request`, `approved` (the digest approved), `moved` or `denied` (the roots), `rules` (by root, for a denial), `holder` (the run applying them, for `held-by-another-apply`) |

`result` on an approval says how it was signed. Whether it counted is the wave's decision under the `approval:` mode at base, and the `apply` or `refused` entry of that wave records it.

| The entry says | What it proves, by mode |
|---|---|
| `who` on an `approval` | `ledger`: the name the approver gave; anyone who can push to `chant/lifecycle` can write any name, and `detail.committed_by` is the commit's author |
| `detail.signer` | `sealed`: the seal's signer; the wave checks it against `.chant/allowed_signers` at base |
| `detail.via`, `pr`, `reviewers` | `pr-review`: the apply job recorded a review of that head by a writer other than the author |
| `detail.relayed_by` | the line's `relayedBy`: a service, such as a chat bot, wrote it for the person `who` names. `ledger` and `pr-review`: the relayer's word that `who` approved; the line counts like any other, and `committed_by` is the account that pushed it. `sealed`: the seal still decides; the line counts only when its seal verifies for `who`, and the seal covers the relayer's name |

## Completeness

| Property | How |
|---|---|
| Append-only | each run reads `audit.jsonl`, keeps every line, and appends the entries whose `id` it lacks; the write is conditional on the copy read, so two runs at once both land |
| Re-derivable | the ledger is read from its git history every run, and the same records give the same `id`s; a new record built from the same sources holds the same entries |
| Checked | `terragucci audit --check` builds the entries again, writes nothing, and exits 1 naming each one the record lacks, such as an approval on the ledger after the last run |
| Revocations kept | removing a line from the ledger revokes it before its wave runs; the record keeps the approval and adds an `approval-revoked` entry with the commit that removed it |
| Replaced reports | a second run of the same wave on the same commit replaces its report in the bucket; the record keeps the entry of the first run when an audit ran between them, so schedule the audit at least as often as waves run |

## Query the record

**Approvals**
    ```bash
    jq -r 'select(.kind == "approval") | [.at, .project, .what, .digest, .who, .result] | @tsv' audit.jsonl
    ```
**Overrides**
    ```bash
    jq -r 'select(.kind == "override") | [.at, .project, .what, .who, (.detail.rules | join(",")), .detail.reason] | @tsv' audit.jsonl
    ```
**Refused and failed**
    ```bash
    jq -r 'select(.kind == "refused" or .result == "failed") | [.at, .project, .what, .result, .evidence.url // .evidence.key] | @tsv' audit.jsonl
    ```
**One wave**
    ```bash
    jq -c 'select(.project == "github.com/acme/network" and .what == "wave-2") | {at, kind, who, digest, result}' audit.jsonl
    ```
**Applies with no approval**
    ```bash
    jq -r 'select(.kind == "apply" and .result == "applied" and .detail.gate == "approved" and .detail.approval == null) | [.at, .project, .what, .digest] | @tsv' audit.jsonl
    ```

Fetch the record with the store's own CLI, such as `aws s3 cp s3://acme-terragucci/reports/audit.jsonl .`, or open the link the job prints for the page.

## The records it reads

| Record | Where | What it says | Written by |
|---|---|---|---|
| A wave asking for approval | `_gates/tf-apply.jsonl` on `chant/lifecycle`, a `"kind":"pending"` line | the wave, the plan digest it asks for, when, and when the request expires | the apply job, when the wave waits |
| An approval | `_gates/tf-apply.jsonl`, any other line, in a commit of its own | the wave, the plan digest it binds, who (`resolvedBy`) and when (`timestamp`) | `terragucci approve`; under `approval: pr-review`, the apply job |
| A policy override | `_gates/policy-override.jsonl` | the root, its plan digest, the rules it overrides, who, when and the reason | `terragucci override` |
| A run's report | the bucket, under one path per commit and stage | every root's plan digest and changes, each wave's set digest, approval state and, when it applied nothing, why (`waves[].refused`) | every `tf-plan`, `tf-apply` wave and `tf-drift` run |
| The index | `index.json` at the project's path | one row per run; `terragucci audit` reads its `tf-apply` rows to find the reports | every upload |

A wave's report names its approval record's branch and path (`waves[].gate`) and never copies it. [Report JSON schema](/terragucci/reference/report-schema/) has every field. Without a bucket, each report is a CI artifact of its job and `terragucci audit` has nothing to read; [Keep reports in a bucket](/terragucci/guides/keep-reports-in-a-bucket/) sets one up.

## Matching an apply to its approval

| Step | Read | Match |
|---|---|---|
| 1 | the `apply` entry: `digest`, `detail.commit` | the digest the wave applied, and the commit it applied from |
| 2 | `detail.approval` | the `id` of the `approval` entry whose `what` and `digest` it applied under |
| 3 | that entry's `evidence.commit` | the commit on `chant/lifecycle` that added the approval line |

A wave whose plans moved after approval applied nothing and exited 4: its entry is `refused`, with the digest approved and the roots that moved ([Fix a refused wave](/terragucci/guides/fix-a-refused-wave/)).

## Retention

| Record | Kept |
|---|---|
| The audit record | your bucket's lifecycle rule; leave `audit.jsonl` out of any expiry |
| The ledger | as long as the `chant/lifecycle` branch; every change is a commit. Protect it against force pushes and deletion ([per forge](/terragucci/guides/approve-a-wave/#push-access-to-chantlifecycle)) |
| Reports and the index in a bucket | your bucket's lifecycle rule; an index keeps its newest 500 rows and the newest of each stage and wave |
| Traces and metrics | your telemetry backend's retention ([Traces and metrics](/terragucci/reference/observability/)) |

---

# The CLI's JSON output

Source: https://intentius.io/terragucci/reference/cli-json/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/reference/cli-json/.
Write a script that runs `npx terragucci plan --json` and branches on the envelope's `exit` and `status` and on `results.roots`, printing each failed root's summary.
Read only. Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

With `--json`, these commands print only one JSON object on stdout.

## The envelope

```json
{
  "schema": 1,
  "command": "init",
  "exit": 0,
  "status": "ok",
  "results": {}
}
```

| Field | Holds |
|---|---|
| `schema` | The envelope version. It changes only when a field is removed or changes meaning; new fields can appear without a bump. |
| `command` | `init`, `reconcile`, `plan`, `stage`, `rollout`, `respond`, `config check` or `query`. |
| `exit` | The process exit code. |
| `status` | `ok` for exit 0, `failed` for 1, `usage` for 2, `waiting` for 3. |
| `results` | What the command found or did, as below. `null` when the command could not run. |
| `error` | Present when `results` is `null`: why it could not run. |

`--json` leaves the [exit codes](/terragucci/reference/cli/#exit-codes) as they are. `stage tf-apply` refuses `--json` and writes [its outcome](#the-apply-outcome) to a file instead, so no envelope carries code 4.

## init

`init --dry-run --json` computes everything and writes nothing.

| Field | Holds |
|---|---|
| `dryRun` | Whether the run wrote files. |
| `roots` | Each root as `path` and `reason`, such as `backend s3`, `cloud block`, `choudoufu live block` (a [choudoufu](/terragucci/concepts/glossary/#choudoufu) estate), `provider aws` or `matches roots glob <glob>`. |
| `layers` | Roots grouped in apply order; roots in one layer can apply together. |
| `binary`, `version`, `forge` | Each as `value` and `reason`, where the reason names the file, flag or detection that decided it. |
| `image` | The CI image the pipeline runs in. |
| `files` | Each file as `path`, `status` (`created`, `updated` or `unchanged`) and `content`. |
| `notes` | Settings the pipeline does not act on, and flags the config overrides. |
| `configNote` | Whether a `terragucci.yml` was used or written. |

## reconcile

`results` holds `mode` (`dry-run` or `apply`) and `projects`, with these fields per project:

| Field | Holds |
|---|---|
| `key` | The project, as `<host>/<path>`. |
| `status` | `unchanged`, `would-change`, `pull-request` or `failed`. |
| `changes` | The files, as in `init`'s `files`. |
| `pullRequest` | The pull request's URL, when one was opened. |
| `error` | Why the project failed. |
| `tips` | On a dry run with `tips` on, advice on the project's setup, as `rule`, `root`, `message` and `url`. |

The exit code is 1 when any project failed.

## plan

`results.roots` has one entry per root, in apply order:

| Field | Holds |
|---|---|
| `root` | the root's path |
| `ok` | whether it planned |
| `summary` | the plan's `Plan:` or `No changes.` line, or the failure |

## stage

| `results` field | Holds |
|---|---|
| `stage` | the stage that ran |
| `change_set` | the set digest |
| `files` | the report files |
| `uploaded` | the bucket copy; `null` without `reports.bucket` |
| `issue` | `tf-drift` only: `action` (`opened`, `updated`, `closed`, `left-open` or `none`), `issue` and `error` |

A root that refused to plan exits 1.

## The apply outcome

On every exit but a usage error, `stage tf-apply` writes its wave's outcome to the file `TG_OUTCOME_JSON` names. With `--rest` the file holds the last wave that ran. The generated apply jobs set the variable when `notify` is on, and `terragucci notify` reads the file. A waiting wave's file carries the `terragucci approve` command that approves it and where its gate's record lives on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle).

```json
{
  "schema": "terragucci.outcome/v1",
  "status": "waiting",
  "exit": 3,
  "wave": 2,
  "roots": ["envs/prod/app", "envs/prod/db"],
  "line": "wave 2 waits: terragucci approve wave-2 --plan jcs1-sha256:9f2c...",
  "set_digest": "jcs1-sha256:9f2c...",
  "gate": { "name": "wave-2", "branch": "chant/lifecycle", "path": "_gates/tf-apply.jsonl" },
  "approval": "waiting",
  "approval_mode": "pr-review",
  "approve_command": "terragucci approve wave-2 --plan jcs1-sha256:9f2c...",
  "waiting_since": "2026-10-08T14:02:11.000Z",
  "review": { "pull_request": 12, "url": "https://github.com/acme/infra/pull/12/files" }
}
```

| Field | Holds |
|---|---|
| `schema` | `terragucci.outcome/v1`. It changes only when a field is removed or changes meaning; new fields can appear without a bump. |
| `status`, `exit` | `applied` (0), `waiting` (3), `refused` (4; 5 when another run's apply holds a resource it changes; 6 when a newer push superseded it) or `failed` (1) |
| `wave`, `roots` | the wave and its roots (units in a Terragrunt repo); `roots` is empty when the repo has no such wave |
| `line` | the line the job's `terragucci/apply` status carries, when the wave wrote one (`TG_OUTCOME`) |
| `set_digest` | the set digest over the roots that change: what an approval binds |
| `gate` | when a gate held the wave: its `name` and the `branch` and `path` of its ledger |
| `approval` | `waiting`, `approved` or `not-required` |
| `approval_mode` | with a gate: `ledger`, `pr-review` or `sealed`, the mode in force at base |
| `approve_command` | waiting, or refused because the plans moved after an approval or a review: the `terragucci approve` command for `set_digest`, with `--sign` under `sealed` |
| `waiting_since` | waiting: when the wave began waiting for an approval of this digest |
| `review` | waiting under `approval: pr-review`: the `pull_request` whose approving review of its head would approve the wave, and the `url` to review it on |
| `refused` | why the wave applied nothing although it planned: `reason` (`approval`, `review`, `override` or `policy`), the digest `approved` and `by` whom, and the `roots` that moved or were denied |
| `policy_denied` | the roots the policy denied, when no override lets them through |
| `failed_roots` | failed: the roots that failed to plan or apply |

## rollout

`results` holds the state the run left the rollout in.

| Field | Holds |
|---|---|
| `kind`, `name` | `module` or `provider`, and the module or provider address. |
| `from`, `to` | The version that moves and the one it moves to. |
| `discovered` | Where `to` was found, when no version was named: a tag, or an OCI repository. |
| `mode` | `dry-run` or `apply`. |
| `status` | `complete`, `opened`, `would-open`, `waiting` or `stopped`, with `stop` saying why it stopped. |
| `waves` | `wave`, `canary` and `parts`: `project`, `roots`, `branch`, `state`, `pullRequest`, `pending`, `failed`, `files`. |
| `roots` | `project`, `root`, `state` (`from`, `to`, `refused` or `elsewhere`), `version`, `reason`. |
| `tips` | Each refused root's tip, as `rule`, `project`, `root` and `message`. |

A part's `state` is `applied`, `nothing-to-move`, `opened`, `would-open`, `open`, `waiting-apply`, `failed`, `closed` or `not-reached`. Exit 3 means waiting; 1 means stopped.

## respond

| `results` field | Holds |
|---|---|
| `event`, `response`, `text` | the event, the response it got and the text printed |
| `skipped`, `data`, `proposals`, `agent_input` | set only when the response has them |
| `exit` | set when the command exits other than 0 |

`respond rollout` with no module puts `mode` and `rollouts` in `data`: for each rollout in flight, `kind`, `name`, `from`, `to`, `wave` (its newest), `waves`, `action` (`ran`, `waiting`, `stopped`, `done` or `failed`), `reason`, `pullRequests`, and `result`, [the rollout](#rollout) when it ran.

Exit 0 when handled, and 1 when a rollout `respond rollout` continued could not run. An unknown event or a missing flag exits 2 with `results` null.

## config check

`terragucci config check [--config <file>]` lists every problem, and for `.ts` checks that folding and running agree.

| `results` field | Holds |
|---|---|
| `file` | the config file read |
| `ok` | whether it has no problems |
| `problems` | a list of strings; a config with problems exits 2 |
| `approval` | for a repo's own config with no problems: `mode` (`ledger`, `pr-review` or `sealed`), `source` (the key, [`identity.gates`](/terragucci/concepts/glossary/#identitygates), or the default) and a `note` when the repo should change something |
| `warnings` | present when there are some: each role that reaches another environment's state, as text; warnings leave the exit code 0 |
| `state_access` | with `oidc.roles` and no problems: one entry per role and stage, with `role`, `stage` (`plan` or `apply`), `environment` (the glob, or `plan_role/apply_role`), `roots`, `states` (the state keys its roots' backends name) and `reads` (other environments' states they read) |

## query

`terragucci query "<statement>" --json` prints the rows the statement returned.

| `results` field | Holds |
|---|---|
| `columns` | the column names, in order |
| `rows` | one object per row, by column name; SQL `NULL` is `null` |
| `tables` | the row count of each table: `inventory`, `changes`, `history`, `audit` and `edges` |

---

# Delivery metrics

Source: https://intentius.io/terragucci/reference/delivery-metrics/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/reference/delivery-metrics/.
Download dora.json from the top of my reports prefix with a read-only identity, validate it against
the JSON Schema the page names, and tell me, per project, the deployment frequency, the lead time with
its split, the change failure rate and the time to restore, and which weeks moved most.
Read only: write nothing to the bucket.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

[`terragucci estate`](/terragucci/guides/see-every-project/#delivery-metrics) reads the [audit trail](/terragucci/reference/audit-trail/) (`audit.jsonl`) and each project's `index.json` from your bucket. It writes the four DORA metrics for each project and the whole estate to `dora.json` beside `estate.json` and to the Delivery section of `estate.html`.

## The metrics

| Metric | terragucci counts | From |
|---|---|---|
| Deployment frequency | applied waves per week | `apply` entries with result `applied` in `audit.jsonl` |
| Lead time | the median time from a change's first plan to its wave applied, split in three (below) | `tf-plan` rows in `index.json`, and the `approval-requested`, `approval` and `apply` entries in `audit.jsonl` |
| Change failure rate | failed applies, plus applied waves whose roots drifted within 7 days, over all applies | `apply` entries with result `failed`, and `tf-drift` rows that found drift |
| Time to restore | the median time from a failed apply to the next apply of those roots, and from drift found to the next drift check that found none | `apply` entries, and `tf-drift` rows |

A refused wave is the gate working, so it is neither an apply nor a failure. Until its approval, a waiting wave is not an apply either.

Infrastructure ships less often than an application. The page shows frequency per project as a trend and never rates a project against DORA's performance tiers.

## The window

Every number covers the newest eight weeks (Monday to Sunday in UTC, current week included). Each week also has its own row, `trend` in `dora.json`, with the same counts for that week alone.

## Lead time and its split

Lead time starts at the first plan. terragucci finds the plan of an applied wave by its commit, or by the wave's digest: a `tf-plan` row lists each wave's set digest and review digest (`wave_digests`), and a merge commit's wave binds the same digest its pull request planned. The clock then starts at the first plan of that pull request.

| Part | From | To |
|---|---|---|
| before the gate | the first plan | the wave asking for an approval; the apply when no gate held the wave |
| at the gate | the wave asking for an approval | the approval |
| after the gate | the approval | the wave applied |

Without a plan in the index, an applied wave has no lead time. The page shows the median of the total and of each part, so the three parts need not add up to the total.

## Change failures and restores

An applied wave counts as failed when its roots drift within 7 days and no later apply of those roots came first. A `tf-drift` row lists the roots that drifted (`drifted_roots`). Rows written before that field existed match any root of their project.

| Event | Incident | Field |
|---|---|---|
| an apply fails | opens one for the roots it failed on | |
| another failure of roots already failing | joins the open incident | |
| an apply applies each of those roots again | closes the apply's incident | |
| the first drift check that finds drift | opens a drift incident, as the [drift issue](/terragucci/guides/turn-on-drift-checks/) does | `drift_since` on the `tf-drift` row |
| the next drift check that finds none | closes it | `drift_cleared` on that row |

Checks of the same commit share one row of the index, so each `tf-drift` row carries the open drift forward. `restore.open` counts the incidents still open.

## Requirements

| Record | Without it |
|---|---|
| `audit.jsonl` | no apply counts: deployments, lead time and failed applies are zero, and the page says so. Run `terragucci audit` before `terragucci estate`. |
| `tf-plan` rows in each `index.json` | no lead time |
| `tf-drift` rows | no drift counts as a failure or a restore |

An index keeps its newest 500 rows. Plans and drift checks older than that drop out of the lead time and the drift counts; the audit trail keeps every apply.

## dora.json

`dora.json` is `terragucci.dora/v1`, with its JSON Schema in the package as `dist/dora.schema.json`.

| Field | What it holds |
|---|---|
| `generated` | when it was built |
| `weeks`, `window` | how many weeks it covers, and the first Monday and the end |
| `drift_window_seconds` | how soon after an apply drift counts against it |
| `audit` | whether `audit.jsonl` was read |
| `estate` | the metrics across every project |
| `projects[]` | each project's metrics, with `project` |

Each set of metrics holds:

| Field | What it holds |
|---|---|
| `deployments`, `per_week` | applied waves in the window, and per week |
| `lead_time` | `changes` counted, `median_seconds`, and the split as `before_gate_seconds`, `at_gate_seconds` and `after_gate_seconds`; `null` when nothing counts |
| `change_failure` | `applies`, `failed`, `drifted` and `rate`; `rate` is `null` with no applies |
| `restore` | `restored`, `open`, `median_seconds`, and how many restores were of applies and of drift |
| `trend[]` | a row per week, oldest first: `week`, `deployments`, `applies`, `failures`, `lead_time_seconds`, `restore_seconds` |

## Gauges

With `OTEL_EXPORTER_OTLP_ENDPOINT` (or the metrics endpoint) set, `terragucci estate` sends one batch of gauges, labelled `project`. The estate's own values carry `project="*"`. The Estate dashboard graphs them in its Delivery row.

| Gauge | Labels |
|---|---|
| `terragucci_dora_deployments_per_week` | `project` |
| `terragucci_dora_lead_time_seconds` | `project`, `segment`: `total`, `before_gate`, `at_gate`, `after_gate` |
| `terragucci_dora_change_failure_ratio` | `project` |
| `terragucci_dora_restore_seconds` | `project` |

A metric with nothing to count, such as a lead time with no plan found, is not sent. [Traces and metrics](/terragucci/reference/observability/) covers the collector and the dashboards.

---

# Migration files

Source: https://intentius.io/terragucci/reference/migration-files/

A migration file is `migrations/<name>.yml` at the top of the repo, and holds one kind of change: `moves`, `backends`, or a `revert`. [Move resources between roots](/terragucci/guides/move-resources-between-roots/) walks through each.

## Moves

```yaml
moves:
  - from: envs/dev/platform
    to: envs/dev/queues
    addresses:
      - aws_sqs_queue.jobs
      - module.search
```

| Key | Holds |
|---|---|
| `moves[]` | one entry per pair of roots; at least one |
| `moves[].from`, `moves[].to` | root directories, relative to the repo; they differ. A root holds `.tf` files, or `*.tf.json` files such as a CDK Terrain stack's `cdktf.out/stacks/<stack>/cdk.tf.json` |
| `moves[].addresses[]` | what moves, to the same address in `to` |

| An address | Moves |
|---|---|
| `aws_sqs_queue.jobs` | that resource, every instance of it |
| `module.service.aws_sqs_queue.jobs` | that resource in that module call, every instance of each |
| `module.search` | every resource and data source in that module call and the modules it calls |

The file's name, without `.yml`, names the gate `tf-migrate <name>`. It starts with a lower-case letter or digit and holds no spaces or capitals. An address with an instance key (`aws_s3_bucket.logs[0]`) or a data source is refused, as is any key the tables do not name. Migrations run in name order, so a date at the front of the name orders them.

## Backends

```yaml
backends:
  - root: envs/dev/platform
    from:
      backend: s3
      config:
        bucket: acme-old-state
        key: envs/dev/platform.tfstate
        region: us-east-1
        use_lockfile: true
```

| Key | Holds |
|---|---|
| `backends[].root` | a root whose backend block, in the same change, names the new backend |
| `backends[].from.backend` | where the state is now: `s3`, `gcs`, `azurerm`, `local`, `pg`, `kubernetes`, `consul`, `http`, `remote`, `cloud` or `file` |
| `backends[].from.config` | that backend's settings, as its block gave them; for `s3`, `bucket` and `key` at least; for `gcs`, `bucket`; for `azurerm`, `storage_account_name`, `container_name` and `key`; for `kubernetes`, `secret_suffix`; for `consul`, `path`; for `http`, `address` |

For these backends, the job reads the state through the root with the old backend in an override file. It writes the state unchanged to the backend the root's code names. The new backend must hold no state for the root. The old state stays where it was; delete it once the move is verified.

### Unversioned backends

The `pg`, `kubernetes`, `consul` and `http` backends (an `http` backend other than GitLab-managed state) keep no versions. A state moves from or to any of them, and a move between roots works on them.

```yaml
backends:
  - root: envs/dev/platform
    from:
      backend: pg
      config:
        conn_str: postgres://db.internal/terraform
        schema_name: platform_old
```

| Step | What the job does |
|---|---|
| plan | `state pull`, through an override file for the source |
| digest | each state's contents; there is no version id |
| write | `state push` under the backend's own lock; the binary refuses a state of another lineage or an older serial. A `kubernetes` backend writes an empty state at init, which the move replaces with `-force` |
| record | each state's address, such as `pg:db.internal/terraform/platform.states` or `kubernetes:<namespace>/<secret_suffix>` |

Credentials stay out of the file: `password`, `token`, `client_key` and `access_token` are refused, and so is a `conn_str` with a password. The job gives them in the backend's own variables, such as `PGPASSWORD` or `KUBE_TOKEN`. The source's lock is not held between the check and the write; the digest check runs just before it. `terragucci migrate revert` refuses these roots, since there is no earlier version to read.

### Workspaces

`remote` and `cloud` read a workspace's current state version over the TFE API, the protocol the `remote` backend and the `cloud` block use. HCP Terraform, Terraform Enterprise, Scalr, OTF and env zero's backend serve it.

```yaml
backends:
  - root: envs/dev/platform
    from:
      backend: cloud
      config:
        hostname: app.terraform.io
        organization: acme
        workspaces:
          name: platform-dev
```

| Key | Holds |
|---|---|
| `hostname` | the API's host; default `app.terraform.io`. The job finds the API through `https://<hostname>/.well-known/terraform.json` |
| `organization` | the organization; for env zero, `<organization id>.<project id>` |
| `workspaces.name` | the one workspace whose state moves; `prefix` and `tags` are refused |

The token is the one Terraform and OpenTofu read for the host: `TF_TOKEN_<host>`, dots as `_` and dashes as `__` (`TF_TOKEN_app_terraform_io`), else `~/.terraform.d/credentials.tfrc.json`. A `token` key in the file is refused. Give the plan and apply jobs the variable as a CI secret.

The digest covers the state version id (`sv-...`) and the state's digest. While it writes, the job holds the workspace's lock, checks that the current version is still the one approved, and unlocks it after. A workspace locked by someone else stops the move. The workspace keeps its versions.

### State files

`file` reads a state file the job can see, for state exported from a platform with no TFE API:

```yaml
backends:
  - root: envs/dev/platform
    from:
      backend: file
      config:
        path: exported/platform.tfstate
```

`path` is relative to the repo, or absolute. The file must be a state of format version 4 with a lineage, a serial and resources. The digest covers its contents, so a file changed after the approval is refused. State holds secrets: put the file in place in the job, not in git.

## Revert

`terragucci migrate revert <name>` writes `migrations/<name>-revert.yml` from the line `_gates/tf-migrate/done.jsonl` keeps for a migration that applied:

```yaml
revert: split-queues
restores:
  - root: envs/dev/platform
    location: s3://acme-state/envs/dev/platform.tfstate
    version_id: "3HL4kqtJlcpXroDTDmJ.rmSpXd3dIbrHY"
    from_version_id: "0dca9e05ea0c465297e4eed760e743f2"
  - root: envs/dev/queues
    location: s3://acme-state/envs/dev/queues.tfstate
    version_id: null
    from_version_id: "3a695fbfaea5493aa48fa9d07b9de2e4"
```

| Key | Holds |
|---|---|
| `revert` | the migration it puts back |
| `restores[].version_id` | the version to put back, read by its id; `null` for a root that had no state, which gets an empty one |
| `restores[].from_version_id` | the version the migration left; a state at any other version is refused, since putting the old one back would undo that later change too |

The revert goes through the same proof, gate and lock as any migration, so revert the code of the migration in the same change. A backend move is put back with a backend move the other way. The command refuses a root on a local backend or a bucket that kept no version, since it has nothing to put back.

## Estates

With [choudoufu](/terragucci/concepts/glossary/#choudoufu) as the binary, when every root a file names has a `live` block:

| File | Change | Refused when |
|---|---|---|
| `moves` | `retag`: each resource's tags are rewritten by `choudoufu live-mv -from-estate`, run in `to` | the roots are one estate, an address is a module call, or `from`'s plan does not destroy the address |
| `backends` | `adopt`: the state in `from` is read once and `choudoufu live-import` stamps each resource it verifies | the state is missing, or the `s3` backend takes no lock file |

A file whose roots mix estates and roots with a state is refused, as is any other binary. An address with `count` or `for_each` moves each instance the source plan destroys.

## The new states

A changed state keeps its lineage and gets the next serial. A root with no state gets a new one at serial 1. Its lineage is derived from the migration and the root, so the same migration planned twice gives the same digest.

The proof plan runs the root's own binary against its new state, through a `terragucci_migrate_override.tf` file that switches the backend to a local file in a data dir of the job's own. The file is removed after the plan, and the root's `.terraform` and real state are left as they were.

## The record

`terragucci-report/migrations/<name>.json` is `terragucci.migration/v1`:

| Field | Holds |
|---|---|
| `name`, `file`, `file_digest`, `change` | the migration file, and its kind: `moves`, `backends`, `revert`, or for estates `retag` or `adopt` |
| `retags[]` | a retag: each instance's `address`, its roots `from` and `to`, `from_estate`, `to_estate`, the `live_id` of the resource, and the `followers` that move with it |
| `stamps[]` | an adoption: each instance of the old state, its `status` as `live-import` verified it, and its `live_id` |
| `moves`, `backends`, `revert` | what it does: the moves; each root and where its state was; the migration a revert puts back |
| `digest` | what an approval binds |
| `status` | `planned`, `proof-failed`, `waiting`, `refused`, `applied` or `failed` |
| `roots[].root`, `backend`, `location` | each affected root and where its state is; for an estate, `estate` and `estate <name>` |
| `roots[].before` | `version_id`, when the backend keeps versions, and `digest`, `null` for a root with no state |
| `roots[].after` | the new state's `digest`, and its `version_id` once written |
| `roots[].source` | a backend move: where the state was read from, its `version_id` and `digest` |
| `roots[].restore` | a revert: the `version_id` put back, `null` for an empty state |
| `roots[].proof`, `roots[].verify` | the resource changes and the binary's summary line, against the new state and, after the write, against the backend |
| `approved_by`, `moved`, `error`, `finished`, `commit` | who approved it, the roots whose state moved, why it stopped, when and at which commit |

---

# Webhook event schema

Source: https://intentius.io/terragucci/reference/notify-event/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/reference/notify-event/.
Write a small HTTP handler that verifies X-Terragucci-Signature over the raw body with a key from the environment, drops a repeated id, and prints the wave, its roots and, for a waiting wave, the approve command.
Read only. Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

When a wave waits, is refused or fails, its apply job posts one event to `notify.webhook`, provided `notify.webhook_key` is set. [Send events to your own webhook](/terragucci/guides/notify-a-chat-channel/#send-events-to-your-own-webhook) sets it up and verifies it. Slack and Teams notices need none of it; it is for a program of yours, such as a relay that turns a chat click into `terragucci approve --plan`.

```json
{
  "schema": "terragucci.notify/v1",
  "id": "4b0c9e...",
  "event": "waiting",
  "sent_at": "2026-10-08T14:02:15.000Z",
  "project": "github.com/acme/infra",
  "forge": "github",
  "repo": "acme/infra",
  "sha": "9d1f0c...",
  "wave": 2,
  "roots": ["envs/prod/app", "envs/prod/db"],
  "run_url": "https://github.com/acme/infra/actions/runs/42",
  "outcome": {
    "schema": "terragucci.outcome/v1",
    "status": "waiting",
    "exit": 3,
    "wave": 2,
    "roots": ["envs/prod/app", "envs/prod/db"],
    "set_digest": "jcs1-sha256:9f2c...",
    "approval_mode": "ledger",
    "approve_command": "terragucci approve wave-2 --plan jcs1-sha256:9f2c..."
  }
}
```

## Headers

| Header | Holds |
|---|---|
| `X-Terragucci-Signature` | `sha256=` and the hex HMAC-SHA256 of the raw body, with the key `notify.webhook_key` names |
| `X-Terragucci-Event` | the `event` |
| `X-Terragucci-Delivery` | the `id` |

An event is never posted unsigned. Check the signature over the bytes received, before parsing them.

## Fields

| Field | Holds |
|---|---|
| `schema` | `terragucci.notify/v1`. It changes only when a field is removed or changes meaning; new fields can appear without a bump. |
| `id` | sha256 over the project, the wave, the event and the set digest (the commit when the wave has none): the same for every post of one wave's event about one digest, so a re-run's post can be dropped |
| `event` | `waiting`, `refused` or `failed` |
| `sent_at` | when the job posted it |
| `project` | the repo as `<host>/<path>` |
| `forge`, `repo`, `sha` | the forge, the repo's path on it, and the commit the wave applied |
| `pr` | the pull or merge request, when a comment's apply posted it |
| `wave`, `roots` | the wave, and its roots; for a refused or denied wave the roots that moved or were denied, for a failed one the roots that failed |
| `run_url`, `report_url` | the run, and the wave's report when [`reports`](/terragucci/guides/keep-reports-in-a-bucket/) serves one |
| `outcome` | the stage's [outcome](/terragucci/reference/cli-json/#the-apply-outcome) as it wrote it, with the `terragucci approve` command that approves a waiting wave |

The JSON Schema ships with the package as `@intentius/terragucci/notify.schema.json`.

---

# Traces and metrics

Source: https://intentius.io/terragucci/reference/observability/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/reference/observability/.
Add the OTLP variables and `dashboards: true` to terragucci.yml as the page says, run `npx terragucci init`, and open a pull request. List the secrets I must add; do not create them.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

Nothing is sent until an endpoint is set; any backend with an OTLP endpoint works.

## Turning it on

terragucci reads the standard OpenTelemetry variables. Set the endpoint for every job in `terragucci.yml`:

```yaml
env:
  OTEL_EXPORTER_OTLP_ENDPOINT: https://otel-collector.example.com:4318
```

### Variables

| Variable | Effect |
|---|---|
| `OTEL_EXPORTER_OTLP_ENDPOINT` | the collector's OTLP/HTTP base URL; traces go to `/v1/traces` and metrics to `/v1/metrics` |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | one signal's full URL, used as given |
| `OTEL_EXPORTER_OTLP_HEADERS` | `key=value` pairs sent with every request, such as an API key |
| `OTEL_TRACES_EXPORTER=none`, `OTEL_METRICS_EXPORTER=none` | turn one signal off |
| `OTEL_SDK_DISABLED=true` | turn both off |
| `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES` | the service name (default `terragucci`) and extra resource attributes |
| `TRACEPARENT` | the stage's trace joins this one, when your CI starts a trace of its own |

### Headers and secrets

| Setting | Value |
|---|---|
| protocol | OTLP/JSON over HTTP, so the collector's port 4318, not gRPC |
| keys | a CI secret named by `telemetry: { headers_secret: OTLP_HEADERS }`; the generated workflows set `OTEL_EXPORTER_OTLP_HEADERS` from it on the plan, apply and drift jobs |
| a fork's pull request | gets no secrets |
| GitLab | mark the variable masked |
| an unreachable collector | never fails a stage |

## The trace

```
terragucci tf-plan          project, commit, binary, change set, totals
  wave 2                    set digest, approval
    root envs/prod/payments plan digest, changes by action, status
      tofu init
      tofu plan             the binary's own spans, under this one
      tofu show
```

### Spans from the binary

Each binary run is a span, passed as `TRACEPARENT`. OpenTofu and [choudoufu](/terragucci/concepts/glossary/#choudoufu) nest theirs in it; Terraform starts its own, tagged `terragucci.trace_id`, `terragucci.span_id` and `terragucci.root`.

The binary exports to a loopback receiver, OTLP over HTTP only, which forwards batches to your collector.

## Timings

With `binary: choudoufu`, the OpenTofu fork from the team behind terragucci ([set it up](/terragucci/guides/use-a-binary/#choudoufu)), the report also times each provider call, sums timings by resource type on a large estate, and times every state lock wait.

### Report contents

Each plan, drift and wave report lists where the time went, even without an endpoint:

- roots by wall time, slowest first, with each one's plan time and, in a wave, its apply time;
- the slowest resource instances in each root, with their refresh time;
- the time of each provider call, with the resource it was for;
- provider start-up;
- waits for a state lock, from [choudoufu](#state-lock-waits) on a backend that locks.

Past a span budget (`CHOUDOUFU_TRACE_DETAIL`, `CHOUDOUFU_TRACE_SPAN_BUDGET`) choudoufu sums timings by resource type or provider method, and the report says so.

choudoufu adds two more:

| Timing | Sent by | Spans | In `report.json` |
|---|---|---|---|
| provider calls | choudoufu | `tfplugin5.Provider/<method>` and `tfplugin6.Provider/<method>`, with `rpc.method` | `roots[].timings.provider_calls` |
| summed timings | choudoufu, once a walk passes its span budget (2000 by default) | `Aggregate: <span name>` | `roots[].timings.aggregates` |

### Timings by binary

| Binary | What the report gets |
|---|---|
| Terraform | no traces; the report says so |
| OpenTofu | a span for each resource instance it plans or applies, so the report lists the slowest resources |
| [choudoufu](/terragucci/concepts/glossary/#choudoufu) | what OpenTofu gives, plus provider calls, summed timings past the span budget, and [state lock waits](#state-lock-waits) |
| Terragrunt | a unit's time from Terragrunt's run report; a `TG_TF_PATH` wrapper points each plan at the receiver |

### State lock waits

On a root whose backend locks (S3 with `use_lockfile`, say), choudoufu ([set it up](/terragucci/guides/use-a-binary/#choudoufu)) records each wait as a `State lock wait` span with its attempts. It shows in the report and in `terragucci_lock_wait_seconds`. An estate with a record store takes no lock, so it shows no waits ([locking with choudoufu](/terragucci/concepts/locking-and-staleness/#with-choudoufu)).

| Run | State lock wait |
|---|---|
| a Terragrunt plan | up to five minutes (`-lock-timeout=5m`) |
| a `tf-apply` wave's plan and apply | up to five minutes (`-lock-timeout=5m`) |

`TF_CLI_ARGS`, `TF_CLI_ARGS_plan` or `TF_CLI_ARGS_apply` set a different wait. A wave writes its report to `terragucci-report/` and the `reports` bucket when set.

The HTML report shows them under "Where the time went", and `report.json` carries `timings` and `roots[].timings`; see [Report JSON schema](/terragucci/reference/report-schema/).

## The metrics

### Exported metrics

A stage pushes its metrics once, when it ends; point Prometheus exporter or remote write on your collector at them. A `tf-apply` wave sends `terragucci_root_apply_seconds`, `terragucci_provider_init_seconds`, `terragucci_lock_wait_seconds` and the `terragucci_wave_*` gauges. All are gauges with `project` and `stage` labels, plus those below.

### Metric table

| Metric | Labels | Answers | Series per project and stage |
|---|---|---|---|
| `terragucci_stage_duration_seconds` | `result` | how long each stage takes, and whether it failed | one per stage and result |
| `terragucci_roots_planned` | | how many roots a change touches | one |
| `terragucci_root_plan_seconds` | `root` | the slowest roots | one per root |
| `terragucci_root_apply_seconds` | `root`, `wave` | the slowest root applies; sent by a `tf-apply` wave | one per root and wave |
| `terragucci_plan_changes` | `action` | creates, updates, replaces and deletes, over time | one per action |
| `terragucci_plan_groups` | | how far a change folds | one |
| `terragucci_binary_version` | `binary`, `version` | the binary versions in use across repos | one per binary version in use |
| `terragucci_last_run_seconds` | | when each stage last ran, in Unix seconds | one |
| `terragucci_roots_changed` | `pull_request` on a plan | how many roots a pull request changes | one per pull request, which grows with every pull request |
| `terragucci_tips` | `rule` | tips by rule | one per rule |
| `terragucci_module_pin` | `root`, `module`, `version` | which version of each module each root pins | one per root, module and version, which grows with every version a root has pinned |
| `terragucci_provider_init_seconds` | `root`, `provider` | provider start-up | one per root and provider |
| `terragucci_lock_wait_seconds` | `root` | time spent waiting for a state lock | one per root that waited |
| `terragucci_resource_seconds` | `root`, `address` | the run's slowest resources | up to the ten slowest resources of a run, so the addresses change from run to run |
| `terragucci_drift_roots` | | roots a drift run found drifted | one |
| `terragucci_drift_since_seconds`, `terragucci_drift_clear_seconds` | | when the open drift was first found (its drift issue opened), and when a drift run last found none | one each |
| `terragucci_wave_roots` | `wave` | roots in a `tf-apply` wave | one per wave |
| `terragucci_wave_waiting_since_seconds`, `terragucci_wave_settled_seconds` | `wave` | when a wave started waiting for its approval, and when it last stopped waiting | one per wave |
| `terragucci_dora_deployments_per_week`, `terragucci_dora_change_failure_ratio`, `terragucci_dora_restore_seconds` | `project` only, `*` for the estate; sent by `terragucci estate` | the [delivery metrics](/terragucci/reference/delivery-metrics/) | one each per project |
| `terragucci_dora_lead_time_seconds` | `project` only, and `segment`; sent by `terragucci estate` | the median lead time and its split | four per project |

### Label cardinality

`pull_request`, `address` and `version` are unbounded, so a long-retention Prometheus grows with them. The Change review dashboard needs `pull_request` and the Runs dashboard needs `address`; dropping either empties those panels.

### Run outcome

The stage span's `terragucci.result` is `success` or `failure` for a plan or drift run, and one of `applied`, `nothing`, `waiting`, `refused` and `failed` for a wave.

### Resource attributes

Metrics carry only `terragucci.project` and `service.version` as resource attributes, and spans also carry `vcs.ref.head.revision` and `cicd.pipeline.run.url.full`.

## Trace links

`report.json` records the run's trace id as `run.trace_id`, and the HTML report shows it. Set `telemetry.trace_url` to a link with `{trace_id}` in it and the report links the trace instead:

```yaml
telemetry:
  trace_url: "https://grafana.example.com/explore?left=%7B%22datasource%22:%22tempo%22,%22queries%22:%5B%7B%22query%22:%22{trace_id}%22%7D%5D%7D"
```

The stage span carries the run's `report.html` address as `terragucci.report.url` when [`reports.url`](/terragucci/reference/report/#report-storage) is set.

## Dashboards and alerts

### Generated files

With `dashboards: true`, `init` and `reconcile` write Grafana dashboards and alert rules; `init` leaves files it did not write alone.

```
observability/terragucci/
  grafana/dashboards/<uid>.json                    one per dashboard
  grafana/provisioning/dashboards/terragucci.yaml  the provider that loads them
  grafana/provisioning/alerting/terragucci.yaml    the SLO burn-rate alerts, as Grafana-managed rules
  prometheus/terragucci.rules.yml                  the SLO recording rules and alerts, and the pipeline alerts
```

### Dashboards

`init` writes nine dashboards, the six below and one for each of the three SLOs.

| Dashboard | Shows |
|---|---|
| Pipeline health | runs per hour, errors and duration for each stage and project, and runs by result |
| Change review | roots changed and groups for each pull request, and creates, updates, replaces and destroys over time |
| Rollouts and waves | waves waiting for an approval and for how long, wave runs by result, and how many roots pin each module version |
| Drift | drifted roots by project, how old the open drift is, and roots corrected |
| Estate | roots per project, the binary and terragucci versions each runs, the delivery metrics `terragucci estate` sends, module pins and tips by rule |
| Runs | the slowest roots, root applies and resources, provider start-up, lock waits, stage durations, and the trace of each run from Tempo |
| One per SLO | the SLI against its objective, the error budget left and the burn rates |

### SLOs and alerts

The SLOs, over 28 days: plans finish within ten minutes 95% of the time, wave applies succeed 99%, drift is corrected within a day 90%.

| Alert | Fires when |
|---|---|
| `TerragucciDriftOld` | a project's open drift is older than `drift_age` |
| `TerragucciWaveWaiting` | a wave has waited for its approval longer than `wave_wait` |
| `TerragucciApplyFailed` | an apply failed in the last hour |
| `TerragucciWaveRefused` | a wave was refused in the last hour because its plans moved |
| `TerragucciDriftStopped` | a project's drift run has not run for `schedule` |

### Dashboard settings

| Key under `dashboards` | Default | Meaning |
|---|---|---|
| `dir` | `observability/terragucci` | where the files go |
| `prometheus` | `prometheus` | the uid of the Grafana datasource reading the Prometheus that holds the metrics |
| `tempo` | `tempo` | the uid of the Grafana datasource reading Tempo |
| `folder` | `terragucci` | the Grafana folder for the dashboards and the Grafana-managed rules |
| `path` | `/var/lib/grafana/dashboards/terragucci` | where Grafana finds the dashboard files |
| `drift_age`, `wave_wait`, `schedule` | `1d`, `4h`, `2d` | the alert thresholds |

Mount `grafana/provisioning/` under `/etc/grafana/provisioning/` and `grafana/dashboards/` at `path`. Add `prometheus/terragucci.rules.yml` to `rule_files`. Page from the alerting file or the `ErrorBudgetBurn` alerts, not both.

### Span metrics

The dashboards read span metrics from a `spanmetrics` connector in your collector:

```yaml
connectors:
  spanmetrics:
    namespace: terragucci.spans
    dimensions:
      - name: terragucci.stage
      - name: terragucci.project
      - name: terragucci.result
    resource_metrics_key_attributes: [service.name, terragucci.project]
    histogram:
      unit: s
      explicit:
        buckets: [5s, 15s, 30s, 60s, 120s, 300s, 600s, 1200s, 1800s, 3600s]
```

Only the Runs dashboard's trace list needs Tempo.

### Links to reports

With `reports.url` set, the Runs dashboard links each trace to `traces/<trace id>.html` and Estate links each project to its report index.

---

# The generated pipeline

Source: https://intentius.io/terragucci/reference/pipeline/

## Applies side by side

Two pushes that change different roots apply at the same time; none cancels another (`apply-per-root`). A root's own applies take turns at its backend's state lock, each waiting up to `-lock-timeout` (5 minutes unless `TF_CLI_ARGS` sets one), so keep a backend that locks: an S3 backend with `use_lockfile` or a DynamoDB table. With [choudoufu](/terragucci/concepts/glossary/#choudoufu) a wave waits only for a run changing one of its own resources ([two applies of one estate](/terragucci/concepts/locking-and-staleness/#two-applies-of-one-estate)).

| Forge | Apply jobs |
|---|---|
| GitHub | in no concurrency group |
| GitLab | in no resource group; with `waves.jobs`, the lock on the remote that a split wave's jobs hold |
| Forgejo | each push to the default branch runs in a group of its own commit, so a later push neither cancels nor waits for an earlier one; other branches' runs, and each pull request's comments, still wait in a group of their own |

Up to Forgejo `16.0.5`, a waiting run can stay stuck with the runner idle after the run ahead of it ends, when that run's last job was skipped or the run was cancelled before any job started. Forgejo hands the waiting job out once any other job in the instance ends or forgejo-runner restarts.

| Rule | What happens |
|---|---|
| [`waves.jobs`](/terragucci/concepts/waves-and-approvals/#a-wide-wave-across-jobs) above 1 | every apply job of the pipeline takes the lock on the remote, held by the run (on GitLab, the pipeline) rather than by one job, so a wave's share jobs apply side by side while another such run's apply waits |
| Stand-down | a push's wave whose commit is no longer the branch tip stands down: at the start of its job on GitHub and Forgejo, and on every forge again once its gate let it through, before it applies. The newer push applies the whole tree (`apply-stand-down`) |
| Another run's resources | with choudoufu, a push's wave waits for a run applying a resource it changes, then plans again; the apply a comment starts is refused and its reply names that run |
| Pull request locks | none under the defaults `apply.when: merge` and `locks: apply`; with [`locks: plan`](#plan-locks), from a pull request's first plan; under `apply.when: pull-request`, an applying pull request or one a writer comments `/terragucci lock` on locks the roots it reaches (in a Terragrunt repo, the units) |
| Parallelism | `tf-plan`, `tf-drift` and `tf-apply` plan and apply a layer's or wave's roots at once, up to `parallelism`: 3 for GitLab-managed state, 4 otherwise, and 16 units for Terragrunt's `run --all` on other backends |
| State lock | `tf-plan` and `tf-drift` plan with `-lock=false`, so a pull request plan or a drift run never waits for an apply that holds a root's lock, and never holds one up |
| Provider cache | a stage's roots share one, the job's `TF_PLUGIN_CACHE_DIR` or one of the stage's own, and their inits take turns, so each provider downloads once per job. A root whose `.terraform.lock.hcl` pins its providers at the binary's own registry takes them from the cache. A root without one, or with one that names another registry, takes them from the cache too, with no lock entry to check them against: the job sets `TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE` for it, so its init never downloads over a provider another root's plan is running, and the log counts such roots once. The job log names each download as `<root>: downloaded <provider> v<version>` |

## Resume after an approval

An approval is a commit on `chant/lifecycle`, and a push there starts nothing: the forges run a push's workflows from the pushed branch, which holds only the ledger. Two things start the waiting wave again.

| What | When | How |
|---|---|---|
| [`terragucci approve`](/terragucci/reference/cli/#approve) | right after it records the approval, with your token | GitHub: re-runs the failed jobs of the run that waited (`GH_TOKEN`, `GITHUB_TOKEN` or `gh auth login`). GitLab: retries that pipeline's job of the wave (`GITLAB_TOKEN`). Forgejo, whose API has no re-run: comments `/terragucci apply` on the merged pull request that made the commit (`FORGEJO_TOKEN`). Without a token it says so and the approval still stands. |
| the resume job, with `apply.resume: <minutes>`, whatever `gate` says | within that many minutes | `terragucci resume` reads the ledger. When a waiting wave's digest, or that of a [state migration](/terragucci/reference/migration-files/) wave 1 waits on, has an approval no apply has used, GitHub's and Forgejo's job runs the waves from wave 1 at the default branch's commit, as a comment's apply does, and GitLab's retries the newest push pipeline's first apply job that did not succeed. With nothing to resume it stops before any credential. |

Neither approves anything; the wave's gate decides again against the plans it makes now.

| Forge | The resume job |
|---|---|
| GitHub | `.github/workflows/terragucci-resume.yml`, on its own schedule, which `init` writes; GitHub may start a scheduled run a few minutes late |
| Forgejo | `.forgejo/workflows/terragucci-resume.yml`, the same |
| GitLab | the `resume` job in the pipeline, for a pipeline schedule you create with the variable `TERRAGUCCI_SCHEDULE=resume`, every `apply.resume` minutes |

GitHub and Forgejo schedule it as the cron `*/<apply.resume>`: `60` runs hourly, and a value that does not divide 60 also runs on the hour. Each run costs a short job even when nothing waits.

## Stopped applies

A gated wave whose approved apply was killed or failed plans again when it next runs. Under [choudoufu](/terragucci/concepts/glossary/#choudoufu), every resource whose apply returned already has its record, so the plan holds only the rest. The wave applies it under the same approval when each change is one the approval covered, unchanged, and every other approved change is done in the records. Otherwise it waits for an approval of the plans it makes. choudoufu's apply still re-reads each resource before it writes.

The resume job applies the rest of a killed apply once the run that applied is gone. A failed apply resumes when its job runs again. With stock OpenTofu or Terraform, a plan that differs from the approved one needs its own approval.

## Apply from a comment

On GitHub and Forgejo, `/terragucci apply` on a merged pull request runs `apply-comment` from the default branch's workflow. It takes the push lock and runs `tf-apply` on the merge commit with the apply role. Forgejo's job also skips a merge commit that a later apply superseded.

The comment approves nothing; a gated wave still needs its approval record, sealed under `approval: sealed`. [Apply a merged pull request](/terragucci/guides/re-plan-from-a-comment/#apply-a-merged-pull-request) has the steps.

## Ignored comments

Every comment command is checked before any credential is used. A failed check stops the job, and the reply starting `terragucci:` names it. On GitLab, with [`comments:`](/terragucci/guides/re-plan-from-a-comment/) set, the `comments` job runs the checks in the GitLab column on each merge request note.

| Check | `plan` | `apply`, merged PR | `apply`, open PR | `lock` | `agent` | GitLab note |
|---|---|---|---|---|---|---|
| The commenter has write access | yes | yes | yes | yes | yes | Developer or above |
| The comment is new; an edit does not run it again | yes | yes | yes | yes | yes | yes |
| The comment is one line in a [form the job accepts](/terragucci/guides/re-plan-from-a-comment/#comment-forms) | yes | yes | yes | yes | yes | yes |
| The head is in this repository, not a fork | yes | yes | yes | yes | yes | yes |
| The pull request is open | yes | merged instead | yes | yes | yes | `plan`; merged instead for `apply`; open for `apply`, `lock` and `unlock` with `apply.when: pull-request` |
| `apply.when` is `pull-request` | | | yes | yes | | `lock`, `unlock`, and `apply` on an open merge request |
| `agent.comment` is set | | | | | yes | `agent` |
| The base is the default branch | | yes | yes | yes | | `apply` |
| The head is not the default branch | | | | | yes | `agent` |
| A named root is a root of the pipeline | yes | | | | | `plan` |
| A named wave exists | | yes | yes | | | `apply` refuses `wave-<n>` |
| The merge commit is still on the default branch | | yes | | | | |
| At most 50 commits reached the default branch after the merge commit | | yes | | | | |
| No later commit on the default branch has an apply of its own (the reply links it) | | yes | | | | `apply` |
| `approved`: a reviewer other than the author approved the head, and no reviewer's last review asks for changes | | | `apply.requires` | | | open `apply`: after the latest push |
| `checks`: no status or check on the head failed or is running | | | `apply.requires` | | | open `apply` |
| `terragucci/plan` passed on the head | | | yes | | | open `apply` |
| `mergeable`: the forge reports no conflicts, and on GitHub no branch protection blocks the merge | | | `apply.requires` | | | open `apply`: `detailed_merge_status` is `mergeable` |
| The head did not move while the comment was read | | | yes | yes | | open `apply`, `lock`: `mr-apply` refuses a `TERRAGUCCI_HEAD` that is not the head |
| `undiverged`: the head contains the default branch as it is now | | | `apply.requires` | | | open `apply` |
| The pull request does not change the pipeline file | | | yes | | | open `apply`: `.gitlab-ci.yml` and `.gitlab/terragucci.yml` |
| No other open pull request holds a lock on a root the change reaches | | | yes | yes | | open `apply`, `lock`, in `mr-apply` |
| The ask is at most 2000 characters, with no control characters | | | | | yes | |

A cell that reads `apply.requires` is checked when [`apply.requires`](/terragucci/reference/config/#apply-before-merge) lists it, and it lists all four by default. A `plan` or `agent` comment from someone without write access gets no reply at all. `/terragucci unlock` needs only write access, and `apply.when: pull-request` or `locks: plan`.

No comment approves a wave. These verbs are refused by name: `approve`, `merge`, `destroy`, `import`, `state`, `force-unlock`.

## Apply before merge

With [`apply.when: pull-request`](/terragucci/reference/config/#apply-before-merge) in `terragucci.yml`, `init` writes these jobs on GitHub and Forgejo in place of the per-wave apply jobs:

| Job | Runs on | Does |
|---|---|---|
| `apply-comment` | `/terragucci apply [wave-<n>]`, `/terragucci lock` or `/terragucci unlock` on an open pull request | checks the [open-PR column](#ignored-comments), locks the roots the change reaches, and applies the head wave by wave with the apply role while no other apply runs; for `lock`, checks the `lock` column and takes the locks with no credential and no apply; for `unlock`, releases its locks |
| `pr-merge` | with `apply.merge: auto`, after `apply-comment` applied every wave | merges while the head is still the applied commit and approved by a reviewer other than its author, then releases the locks |
| `confirm` | each push to the default branch | plans every root (every unit, after the Terragrunt caches and plan roles) and applies nothing; its `terragucci/apply` status fails naming roots that plan a change |

On GitLab a merge request's pipeline is built from its own `.gitlab-ci.yml`, so the apply runs in a default-branch pipeline that the [`comments`](/terragucci/guides/re-plan-from-a-comment/) job starts. That pipeline runs these jobs:

| Job | Runs on | Does |
|---|---|---|
| `comments` | the comments schedule | for `/terragucci apply` on an open merge request, checks the open-PR column; then, for `apply`, `lock` or `unlock`, starts a pipeline on the default branch with the merge token and `TERRAGUCCI_MR`, `TERRAGUCCI_NOTE` and `TERRAGUCCI_HEAD` |
| `mr-apply` | that pipeline alone | reads the note, its author, the merge request and its head from GitLab, refuses a head other than the variable's, checks the open-PR column again, locks, and applies the head wave by wave under the apply group; posts no status on the head |
| `pr-merge` | with `apply.merge: auto`, after `mr-apply` | merges once `mr-apply`'s reply says every wave of that head applied in this pipeline, and the head is still approved; it takes no artifact from `mr-apply` |
| `confirm` | each push to the default branch | as above |

Without `comments` and `apply.merge_token_env`, `init` and `config check` refuse it on GitLab ([GitLab](/terragucci/reference/config/#apply-before-merge-on-gitlab)).

Each wave reads its approval mode and gate rule from the default branch, and its signers file and config too. A run that stopped at a wave never merges.

| Merge setting | Who merges |
|---|---|
| `apply.merge: manual` (default) | a person |
| `apply.merge: auto` with `apply.merge_token_env` | `pr-merge`, the only job given that token; it runs no pull request code |
| `apply.merge: auto` with no merge token | `pr-merge` with the job's own token: Forgejo refuses it; on GitHub the merge starts no workflow, so the next push confirms it; GitLab needs the token |

In a Terragrunt repo, `apply-comment` (on GitLab, `mr-apply`) runs the waves of units with `--terragrunt`, as the apply jobs do. It locks units; [Locks](/terragucci/guides/apply-before-merge/#locks) says which. They are stored in `_locks/tf-apply.json` on the [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) branch; a lock whose pull request merged or closed counts as released.

## Plan locks

With [`locks: plan`](/terragucci/reference/config/#plan-locks), `init` adds one job on GitHub and Forgejo:

| Job | Runs on | Does |
|---|---|---|
| `pr-lock` | `pull_request_target` (opened, reopened, synchronize, closed); `/terragucci plan`; under `apply.when: merge` also `/terragucci lock` and `/terragucci unlock` | locks the roots the head reaches, releases its own plan locks on roots the head no longer reaches, and posts `terragucci/lock` on the head; on `closed` or `unlock`, releases the pull request's locks |

| What it has | What it never has |
|---|---|
| the default branch's workflow and checkout; `contents: write` (to push `_locks/tf-apply.json` to `chant/lifecycle`), `statuses: write`, `pull-requests: write` | a checkout of the pull request, a cloud role, an OIDC token, a run of the binary or Terragrunt |

It reads the change as data from git: the diff, and in a Terragrunt repo each unit's `terragrunt.hcl`. A fork's pull request takes no lock. A head that moved since the event is locked as the forge has it now. The `fmt` job commits formatting with its own token, and that push starts no run. With `locks: plan` the `fmt` job therefore runs the same step itself and answers the lock on the formatted head, for which it gets `statuses: write` and `pull-requests: write`. Under `apply.when: merge` the lock gates nothing by itself: require `terragucci/lock` in branch protection to hold the merge.

### Pull request code access

The pull request's own code (providers, modules, external data sources) runs in the applying job and reaches:

| Thing | Reachable | Note |
|---|---|---|
| The apply role | yes | the job applies with it |
| A [forge token](/terragucci/reference/environment/#forge-tokens) in the stage's environment | no | stages start the binary and Terragrunt without one |
| The job's own credentials | yes | through the git checkout and the job's parent processes |
| `contents: write` on the repo | yes | the job holds it, so require a reviewed pull request for pushes to the default branch |
| Commit statuses on the head | yes | the code can set them, so the status check proves only that none failed or is running |
| The merge token | no | only `pr-merge` gets it |

The guard against all of this is a reviewer's approval of the head as the forge records it.

## Statuses and stale plans

Each stage posts one commit status per run; `terragucci/plan` carries the counts of roots, groups and destroys. Branch protection can require `terragucci/plan` or `terragucci/apply`.

| `terragucci/apply` when | GitHub and Forgejo | GitLab |
|---|---|---|
| wave 1 starts | pending, `applying` | running, `applying` |
| a wave waits for its approval (exit 3) | pending, with the approve command | failed, with the approve command |
| a wave is refused (exit 4) or fails | failure | failed |
| the last wave applies | success | success |

GitLab refuses to move a running status back to pending, and a status left running keeps the pipeline running. The next status a retried wave posts replaces the failed one.

With `approval: pr-review` (GitHub and Forgejo) the pipeline also posts `terragucci/approval` on a pull request's head, from the plan job after its note and from an `approval` job that runs on each review of the pull request (`pull_request_review`). Require it in branch protection so a change that a gated wave will wait on merges only once reviewed.

| `terragucci/approval` when | State |
|---|---|
| no wave of the plan waits for an approval | success |
| a wave waits, and a writer other than the author approved the head with nobody asking for changes | success, naming the reviewers |
| a wave waits, with no such approval of the head | pending |

When the default branch changes a root that a pull request's plan note covers, the note is marked stale. Pushing to the pull request plans it again.

## Runners

[`runner`](/terragucci/reference/config/#runners) places each job by its stage:

| Stage | Jobs |
|---|---|
| `plan` | plan, re-plan |
| `apply` | every `apply-` job (the waves, their shares, `apply-comment`), `confirm`, `resume`, `ephemeral`, the ephemeral sweep, and on GitLab `mr-apply` |
| `drift` | drift |
| `default` | every other job: check, the note jobs, `fmt`, `tips`, `version-bump`, `publish`, the rollout, comments, agent and review jobs |

A job whose stage `runner` leaves out runs on `default`, and with no `default` keeps the forge's: `ubuntu-latest` on GitHub, `docker` on Forgejo, any untagged runner on GitLab. Jobs from `own_jobs` keep the runner they name.

## Credentials

Set `oidc` and jobs trade the forge's identity token for cloud credentials, so CI holds no long-lived keys. Each cloud takes one identity for plan and one for apply; one identity for both is rejected.

| Job | Identity | Subject the job carries |
|---|---|---|
| plan | the read-only plan identity | the pull request's on GitHub and Forgejo, the source branch's on GitLab |
| re-plan, drift, `confirm` | the read-only plan identity | the default branch's |
| apply, `apply-comment` | the apply identity | the default branch's |
| a fork's pull request | none: it gets no plan job | |

**AWS**

```yaml
oidc:
  plan_role: arn:aws:iam::111122223333:role/terragucci-plan
  apply_role: arn:aws:iam::111122223333:role/terragucci-apply
```

| Item | Value |
|---|---|
| Token audience | `sts.amazonaws.com`, or `oidc.audience` |
| The job sets | `AWS_ROLE_ARN` and `AWS_WEB_IDENTITY_TOKEN_FILE` |
| Trust | an IAM OIDC provider for the issuer; each role allows `sts:AssumeRoleWithWebIdentity` on `aud` and `sub`: the pull-request and default branch subjects for plan, the default branch's alone for apply |

Root globs give each environment its own pair of roles:

```yaml
oidc:
  roles:
    "envs/prod/**": { plan: arn:aws:iam::111122223333:role/prod-plan, apply: arn:aws:iam::111122223333:role/prod-apply }
    "envs/dev/**": { plan: arn:aws:iam::444455556666:role/dev-plan, apply: arn:aws:iam::444455556666:role/dev-apply }
```

The job fetches its token as before and carries the stage's roles in `TERRAGUCCI_ROOT_ROLES`. The stage sets `AWS_ROLE_ARN` to the role of the first glob a root matches, for:

- the root's init, plan and apply
- its [steps](/terragucci/guides/run-steps/)
- the state version an apply records
- a [migration](/terragucci/reference/migration-files/)'s reads and writes of its state

A root no glob matches runs with `plan_role` or `apply_role`. [Keep each environment's roles to its own state](/terragucci/guides/scope-state-access/) shows the policy each role needs and the warnings `config check` gives.

**GCP**

```yaml
oidc:
  gcp:
    workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/forge/providers/ci
    plan_service_account: terragucci-plan@shop.iam.gserviceaccount.com
    apply_service_account: terragucci-apply@shop.iam.gserviceaccount.com
    # token_url: https://sts.europe-west3.rep.googleapis.com/v1/token   # a regional STS endpoint
```

| Item | Value |
|---|---|
| Token audience | `https://iam.googleapis.com/` followed by `workload_identity_provider` |
| The job sets | `GOOGLE_APPLICATION_CREDENTIALS`, an `external_account` file that reads the token from `credential_source.file` and exchanges it at `gcp.token_url` (default `https://sts.googleapis.com/v1/token`) for the stage's service account |
| Trust | a pool and OIDC provider mapping `google.subject=assertion.sub`, admitting only your repo; grant `roles/iam.workloadIdentityUser` on each service account to `principal://iam.googleapis.com/projects/<number>/locations/global/workloadIdentityPools/<pool>/subject/<subject>`: pull-request and default branch for plan, default branch alone for apply |

**Azure**

```yaml
oidc:
  azure:
    tenant_id: 00000000-0000-0000-0000-000000000001
    subscription_id: 00000000-0000-0000-0000-000000000002
    plan_client_id: 00000000-0000-0000-0000-000000000003
    apply_client_id: 00000000-0000-0000-0000-000000000004
    # audience: api://AzureADTokenExchangeUSGov   # a sovereign cloud's audience
```

| Item | Value |
|---|---|
| Token audience | `api://AzureADTokenExchange`, or `azure.audience`: `api://AzureADTokenExchangeUSGov` for Azure US Government, `api://AzureADTokenExchangeChina` for Azure China |
| The job sets | `ARM_USE_OIDC=true` with `ARM_CLIENT_ID`, `ARM_TENANT_ID`, `ARM_SUBSCRIPTION_ID` and `ARM_OIDC_TOKEN_FILE_PATH` |
| Trust | a federated credential on each app registration or user-assigned managed identity for the issuer, the audience and the exact subject: one for the pull request and one for the default branch on plan, the default branch alone on apply |

The job asks the forge for one token per cloud. The state backend of each cloud reads the same settings as its provider.

| Forge | The job gets its token through |
|---|---|
| GitHub | `id-token: write` |
| GitLab | one `id_tokens` entry per cloud |
| Forgejo | `enable-openid-connect: true`, which needs Forgejo 15 and Forgejo Runner 12.5 or later; on an older Forgejo, leave `oidc` unset and give the runner static credentials |

Each identity trusts the forge's issuer and checks the token's `sub` claim; [Environment variables and credentials](/terragucci/reference/environment/#cloud-roles-over-oidc) lists the issuer and the exact subjects each role trusts on each forge.

Keep the apply role's trust to the default branch's subject. On GitLab a trust on `ref:*` lets any branch assume it. `apply-comment` runs the default branch's workflow and carries its subject, so apply before merge needs no trust change.

With `reports.bucket` set, the report upload's credentials come from:

| `reports` | Forge | Credentials |
|---|---|---|
| `s3://`, no `role` | GitHub, Forgejo | the plan, re-plan and drift jobs map the secrets `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_SESSION_TOKEN`, empty when missing |
| `az://` | GitHub, Forgejo | the same jobs map the secret `AZURE_STORAGE_KEY`, empty when missing, and otherwise write with `oidc.azure` |
| `gs://` | any | nothing is mapped: the jobs write with `oidc.gcp` |
| no `role` | GitLab | CI/CD variables, read directly |
| `role` set | any | nothing is mapped |

[Keep reports in a bucket](/terragucci/guides/keep-reports-in-a-bucket/) lists the secrets.

### GitLab-managed state

The binary never gets `CI_JOB_TOKEN` ([forge tokens](/terragucci/reference/environment/#forge-tokens)), but a `TF_` variable reaches it as set. Pass the `http` backend's credentials as `TF_` variables in `env:`:

```yaml
env:
  TF_HTTP_ADDRESS: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/infra"
  TF_HTTP_LOCK_ADDRESS: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/infra/lock"
  TF_HTTP_UNLOCK_ADDRESS: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/infra/lock"
  TF_HTTP_LOCK_METHOD: POST
  TF_HTTP_UNLOCK_METHOD: DELETE
  TF_HTTP_USERNAME: gitlab-ci-token
  TF_HTTP_PASSWORD: "${CI_JOB_TOKEN}"
```

GitLab expands the references in each job. The example names one state, `infra`, for a root with an empty `backend "http" {}` block. For several roots, give each root's block its own `address`, `lock_address` and `unlock_address`; the credentials stay in `env:`. An address in the block also gives a `terraform_remote_state` read of it an [edge](/terragucci/guides/track-cross-state-edges/).

On GitLab-managed state, each apply records the state's [serial](/terragucci/guides/find-a-state-version/#gitlab-managed-state), and [`state export`](/terragucci/guides/export-a-state-version/#gitlab-managed-state), [`unlock-state`](/terragucci/guides/release-a-state-lock/#gitlab-managed-state) and [ephemeral copies](/terragucci/guides/ephemeral-environments/) work as on `s3`.

### The agent comment

With `agent.comment` set, `/terragucci agent <ask>` on a pull request starts the two jobs below. Neither gets a cloud role. On GitLab the `comments` job answers the note and starts them in a default-branch pipeline with `TERRAGUCCI_AGENT_MR`, `TERRAGUCCI_AGENT_NOTE` and `TERRAGUCCI_AGENT_HEAD`. Both read the merge request and the note from GitLab again. GitLab hands every job the project's variables, so the agent runs under `env -i` with only the prompt, the turn limit and the model's key.

| Job | Token | Does |
|---|---|---|
| `agent` | the job's own, read and comment; the agent's step runs without it | checks the [`agent` column](#ignored-comments), checks out the head without credentials, runs the agent command with the prompt on stdin and the model's key in that step alone, and keeps the change as a patch |
| `agent-push` | the secret `agent.token_env` names | in a fresh container, applies the patch to the same head; refuses a patch touching a [guarded path](#paths-an-agent-cannot-change), otherwise pushes it to the head branch without force; replies with the commit or the reason |

The push starts the pull request's plan job, which plans the change with its read-only role. The `replan` job leaves `/terragucci agent` comments to these jobs.

#### Paths an agent cannot change

`agent-push` refuses a patch that touches any of these (matched case-insensitively) and names the paths in its reply.

| Path | Where | Kind |
|---|---|---|
| `.github/`, `.forgejo/`, `.gitea/`, `.gitlab/`, `.gitlab-ci.yml` | repo root | CI |
| `terragucci.yml` (or `.yaml`, `.json`, `.ts`) | repo root | config |
| [`chant.workspace.json`](/terragucci/concepts/glossary/#chantworkspacejson), `.chant/` | repo root | approvals |
| the signers file `.chant/trust.json` names | where it points | approvals |
| the policy directory (`policy.path`, default `policy/`) | repo root | policy |
| `CODEOWNERS` | repo root, `.github/` or `docs/` | code owners |
| `.claude/`, `.cursor/`, `.mcp.json`, `.cursorrules` | repo root | agent instructions |
| `CLAUDE.md`, `AGENTS.md` | any directory | agent instructions |
| `.gitattributes`, `.gitmodules` | any directory | git settings |

### The drift agent

When a drift run opens the drift issue and `agent.drift` is set (GitHub or Forgejo), the jobs below run after the `drift` job against the commit it planned. The drift job's step writes `issue.json` beside its report and says in its outputs whether it opened the issue. Neither job gets a cloud role.

| Job | Token | Does |
|---|---|---|
| `drift-agent` | the job's own, read-only; the agent's step runs without it | checks out the commit without credentials, fetches the drift report, `terragucci drift-agent prompt` writes the prompt, runs the agent command with the prompt on stdin and the model's key in that step alone, and keeps the change as a patch |
| `drift-agent-push` | the secret `agent.token_env` names | in a fresh container, applies the patch to the same commit; refuses a patch touching a [guarded path](#paths-an-agent-cannot-change), otherwise commits it to `terragucci/drift-agent-<issue>`, pushes it without force, opens the pull request and comments its link on the drift issue |

The pull request is planned like any other, and its merge applies through the gate. [Have an agent fix drift](/terragucci/guides/agent-fix-drift/) covers the setup.

### The review

With `review.agent` set on GitHub or Forgejo, `init` also writes the workflow `terragucci-review.yml`. The forge runs it from the default branch, so a pull request that edits it changes nothing until it merges. GitLab keeps the `review` and `review-note` jobs in the pipeline file; they run only in the default-branch pipeline that the `comments` job starts for a merge request's head once its plan job ended (`TERRAGUCCI_REVIEW_MR`, `TERRAGUCCI_REVIEW_HEAD`).

| Forge | Runs on | Waits for the plan |
|---|---|---|
| GitHub | `workflow_run`, when the pipeline's `pull_request` run of a pull request from the repo completes, passed or failed | the run that started it has finished |
| GitLab | the comments schedule's next run, for an open merge request from the project | its plan job has ended |
| Forgejo | `pull_request_target` of a pull request from the repo (opened, reopened, synchronize); Forgejo has no `workflow_run` | the `review` job waits up to 30 minutes for the `plan` job of the pipeline's run of the head, then reviews without its report |

Its two jobs get no cloud role.

| Job | Token | Does |
|---|---|---|
| `review` | the job's own: on GitHub it reads contents, actions and pull requests; the command's step runs without it | checks out the head with the whole history and no credentials kept; `terragucci review prompt` reads the pull request, fetches the plan job's report from the pipeline's run of the head, and writes the prompt from them and the diff, with the instructions from the default branch; runs the review command in the default branch's files with the prompt on stdin and the model's key in that step alone; keeps what it prints, its exit code, and the pull request, head and base it reviewed as the `terragucci-review-<head>` artifact |
| `review-note` | the job's own, to comment | in a fresh container, `terragucci review post` posts the review as one note, or edits the note it posted before |

The note's first line is a human-readable marker with the head and the risk. A `tf-apply` wave reads the risk from the `terragucci-review-<head>` artifact instead, and only from a run of the default branch's review workflow, as [`input.review`](/terragucci/reference/policy/#review). Its GitHub job gets `actions: read` for that. On GitLab the marker also names the review job, and the wave reads that job's `terragucci-review/` artifact once GitLab says the job is `review` in a pipeline of the default branch. [Have a model review a pull request](/terragucci/guides/agent-review-a-pull-request/) covers the setup.

### Terragrunt

In a Terragrunt repo, each environment's roles go by unit glob:

```yaml
terragrunt:
  credentials:
    "live/prod/**": { plan: arn:aws:iam::111122223333:role/prod-plan, apply: arn:aws:iam::111122223333:role/prod-apply }
    "live/dev/**": { plan: arn:aws:iam::444455556666:role/dev-plan, apply: arn:aws:iam::444455556666:role/dev-apply }
```

terragucci's auth provider command uses the job's identity token to hand each unit the role of the first glob its path matches. A unit's own `iam_role` wins, assumed with the same token; terragucci never sets `TG_IAM_ASSUME_ROLE`.

| Cloud | A unit runs as |
|---|---|
| AWS | the role of the first matching glob, or its own `iam_role` |
| GCP | the stage's identity; a unit can set `impersonate_service_account` (the job's account needs `roles/iam.serviceAccountTokenCreator` on it) |
| Azure | the stage's identity; a unit can set `client_id` for a client trusting the same subject |

## Terragrunt jobs

In a Terragrunt repo the same jobs run Terragrunt:

| Job | Runs |
|---|---|
| check | the binary's `fmt -check -recursive -diff .` (for the modules units call), `terragrunt hcl fmt --check` and `terragrunt hcl validate --inputs`, then the policy tests when `policy` is set |
| fmt | after a branch's check fails, the binary's `fmt` and `terragrunt hcl fmt`, pushed to the branch as one commit (`respond.fmt`) |
| plan | `terragucci stage tf-plan`, one `terragrunt run --all` per wave |
| apply | `terragucci stage tf-apply --terragrunt`, one job per dependency layer: plans its units with `terragrunt run --all`, gates on their set digest, applies exactly those saved plans with a second `run --all`. The last job runs with `--rest`, so a layer added after `init` applies there, behind its own gate. With `waves.jobs` a wide layer's job decides and its share jobs apply with `run --all --filter`; when the last layer splits, an `apply-rest` job after its shares runs with `--rest` |

The jobs run Terragrunt without prompts, with `binary` as its tool. Sources and providers stay cached in `.terragrunt-cache/` at the repo root between runs. A repo on GitLab-managed state runs 3 units at once; others run 16.

---

# Policy

Source: https://intentius.io/terragucci/reference/policy/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/reference/policy/.
Write a Rego policy under the policy directory that denies the rule I name, with tests, and open a pull request.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

With `policy` in `terragucci.yml`, `tf-plan` fails each planned root whose plan JSON your Rego denies.

```yaml
policy:
  engine: conftest
  path: policy
```

| Key | Default | Meaning |
|---|---|---|
| `engine` | `conftest` | `conftest` or `opa` |
| `path` | `policy` | the directory of Rego files, inside the repo |
| `namespace` | every namespace for conftest; for opa, `main`, or every package under `terraform.policies` with `input: hcp` | the Rego package whose rules count |
| `input` | `plan` | what `input` holds: `plan`, the bare plan JSON; `hcp`, `{plan, run}` as HCP Terraform's OPA policies read it |
| `source` | none: the repo's own `path` | a shared policy repo at a pinned ref, `git+https://<host>/<path>@<ref>`; see [below](#a-shared-policy-source) |
| `override` | none: no override counts | the forge identities or signers who may let one denied plan through `tf-apply`, read at base; see [below](#overriding-a-denial) |

## A shared policy source

Many repos can share one policy repo. With `source` set, `path` is the directory inside it:

```yaml
policy:
  source: git+https://github.com/acme/policy.git@v3
  path: policy
```

| Part | Meaning |
|---|---|
| `git+https://<host>/<path>` | the policy repo; `git+http://` for a forge on a private network, `git+file://` for a repo on the job's disk |
| `@<ref>` | required: a tag, a branch, or a commit, which pins it exactly |
| `path` | the Rego directory inside the policy repo, default `policy` |

The repo that sets `source` needs no policy directory of its own. Each `tf-plan`, `tf-check` and `tf-apply` job fetches the source at the ref with its own git credentials and logs the commit read. A private policy repo needs a credential the job's git can use, such as a credential helper.

| Case | Result |
|---|---|
| the source cannot be fetched, or the ref is not there | every planned root fails |
| the ref has no `path` directory | every planned root fails |
| a pull request changes `source` | checked against the base's `source`, as for any `policy` key |

### From a control repo

Set `policy` under `defaults` in the [control repo](/terragucci/concepts/control-repo/), or under one project:

```yaml
defaults:
  policy:
    source: git+https://github.com/acme/policy.git@v3
projects:
  github.com/acme/infra: {}
  github.com/acme/network: {}
```

A project's jobs read `policy` from its own `terragucci.yml`, so `reconcile` writes the key there, in a file whose first line says the control repo writes it. `reconcile` fails a project whose `terragucci.yml` sets a different `policy` and names the key to set.

## Writing a policy

A policy is Rego that denies with a message:

```rego
package main

deny contains msg if {
  some rc in input.resource_changes
  rc.type == "aws_s3_bucket_public_access_block"
  rc.change.after.block_public_acls == false
  msg := sprintf("%s must block public ACLs", [rc.address])
}
```

### Rego input

`input` is the unredacted `show -json` of one root. Before a denial or warning reaches the report, note or log, every sensitive value in it, short ones such as `1` included, becomes `(sensitive, redacted by terragucci)`.

Settings by where the policy came from:

| Policy source | Setting |
|---|---|
| written for terragucci | `input: plan`, the default |
| HCP Terraform OPA policy set | `input: hcp`, with `engine: opa` ([below](#hcp-terraform-policy-sets)) |
| Spacelift | `input: plan`, and change `input.terraform` to `input` in the policy |
| Scalr OPA policy group | `input: plan`, and change `input.tfplan` to `input` in the policy; `input.tfrun` has no counterpart |

HCP Terraform, Spacelift and Scalr policies read other paths and deny nothing as written.

### Cost

In `tf-plan` and every `tf-apply` wave, `input.cost` holds the monthly cost of the root and of its wave when [`cost`](/terragucci/guides/estimate-cost/) is set. Under `input: plan` it sits beside the plan's keys (the plan JSON has no `cost` key of its own); with `input: hcp`, beside `plan` and `run`.

| Field | Value |
|---|---|
| `cost.estimator`, `cost.currency` | the estimator's name, such as `infracost`, and its currency |
| `cost.root.monthly_delta` | the change this root's plan makes to its monthly cost |
| `cost.root.monthly_total`, `cost.root.past_monthly_total` | the root's monthly cost after the plan and before it |
| `cost.wave.number`, `cost.wave.monthly_delta`, `cost.wave.monthly_total`, `cost.wave.past_monthly_total` | the root's wave and the same figures summed over its roots estimated; in `tf-plan`, over the roots the change reaches |
| `cost.approve_above` | `cost.approve_above` in the config at base, or `null` |

A figure the estimator could not give is `null`. Without `cost`, `input.cost` is absent. A denial on cost blocks the plan and the wave like any other, and an [override](#overriding-a-denial) can let one plan through.

```rego
package main

deny contains msg if {
  input.cost.wave.monthly_delta > 500
  msg := sprintf("wave %d adds %v %s a month", [input.cost.wave.number, input.cost.wave.monthly_delta, input.cost.currency])
}
```

### Review

With [`review.agent`](/terragucci/guides/agent-review-a-pull-request/) set, `input.review` holds the model's review of the pull request a `tf-apply` wave applies, beside `cost`. `tf-plan` runs before the review, so it has none.

| Field | Value |
|---|---|
| `review.found` | whether a run of the default branch's review workflow kept a review of the pull request's head |
| `review.risk` | `low`, `medium` or `high` from that review; `unknown` when none was found, the model gave none, or its command failed |
| `review.pull_request`, `review.head` | the pull request the commit merged, or the one applied before merge, and its head; `null` for a commit no pull request made |

The wave reads, through the forge's API, the newest `terragucci-review-<head>` artifact kept by a run of the default branch's review workflow:

| Forge | Run read |
|---|---|
| GitHub | a `workflow_run` run of `terragucci-review.yml`; the apply jobs get `actions: read` for it |
| Forgejo | a `pull_request_target` run of it whose event names the default branch as the base, and this pull request and head |
| GitLab | none; there is no review job, so `found` is always `false` |

The artifact must say it reviewed this pull request and head against the default branch. The wave passes over an artifact of that name from any other run, such as the pull request's own pipeline, and logs why. It never reads the note on the pull request, since any run's token can post one, a run of another branch included ([threat model](/terragucci/reference/threat-model/#the-review)). An artifact the forge has expired reads as no review. Without `review.agent`, `input.review` is absent.

```rego
package main

deny contains msg if {
  input.review.risk == "high"
  msg := sprintf("the review of pull request %d says risk high", [input.review.pull_request])
}
```

### Counted rules

| Rule | Effect |
|---|---|
| `deny`, `violation`, `deny_<name>`, `violation_<name>` | fail the root |
| `warn`, `warn_<name>` | warn |

A message is the rule's string or its object's `msg`. Both engines give the same verdict.

Each denial carries its rule's id, which an [override](#overriding-a-denial) names:

| Engine | Rule id |
|---|---|
| `conftest` | the package and rule of the query that denied, such as `main.deny_public_bucket` |
| `opa` | the package and rule, such as `terraform.policies.no_public_buckets.deny` |
| `opa` with a `policies.hcl` | the policy's name, such as `no_public_buckets` |

The job's log and `roots[].policy.rules` in the report list them.

### Namespace matching

If no Rego file outside the tests declares the namespace and has a `deny`, `violation` or `warn` rule, every planned root is refused and the message lists the packages found.

## Denials

| Case | Result |
|---|---|
| a root's policy denies it | the root fails and the job exits 1; the denials and their rule ids go to `roots[].policy` in the report |
| the policy cannot run (no engine, Rego that does not compile) | the root fails |
| a warning | never blocks |

A denial clears when the code changes until the policy passes, or when the policy changes in a pull request your reviewers approve and merge. A listed approver can also override one plan. Responses, agents and comments cannot waive it.

## Overriding a denial

With `override` set, a person it lists can let one denied plan through `tf-apply`. The override is a line on the ledger beside the approvals, and it never edits the policy. `tf-plan` still fails the root.

```yaml
policy:
  path: policy
  override: [github:alice, github:bob]
```

1. The policy denies a root in a `tf-apply` wave. The wave applies nothing and exits 1. It records the denial on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) in `_gates/policy-override.jsonl` and prints the command:

   ```text
   envs/prod/app: policy.override at base lists github:alice, github:bob; one of them can let this plan through with:
     terragucci override envs/prod/app --rule main.deny_public_bucket --reason "<why>"
   ```

2. A listed approver reads the plan and the denial, then runs that command in a checkout, with the reason ([`override`](/terragucci/reference/cli/#override)). It records the override with the reason, with `--sign` under `approval: sealed`.

3. Run the wave's job again. Before applying the root, it marks the override used in `_gates/policy-override/applied.jsonl`; its report and note name the override.

### Override binding

| Part | Effect |
|---|---|
| one root | every other root's denial stands |
| its plan digest | a plan that changes before the override applied gives another digest: the override counts for nothing, the wave applies nothing and exits 4, and the next run asks again. Once a wave applied under the override, the root's next denial is recorded as a new one and exits 1, waiting for its own override |
| the rule ids | `--rule` names exactly the rules that denied the plan; a rule added or gone needs a new override |
| a reason | required; kept on the ledger line and shown in the report |

### Valid overrides

| Case | Counts |
|---|---|
| by someone `override` lists in the config at base, written after the wave recorded the denial, with a reason | yes |
| the same under `approval: sealed` | only when sealed by a key the signers file at base lists for that person |
| by someone not listed, or listed only by the commit being applied | no |
| a line a job wrote, such as a `pr-review` record | no |
| no `override` at base | nothing counts, and no denial is recorded |
| a root the policy could not check (no engine, Rego that does not compile) | never overridden |

Base is the applied commit's first parent, or the pull request's base with `apply.when: pull-request`, as for [approvals](/terragucci/guides/approve-a-wave/#rule-commit). Under `approval: ledger` the line names its approver without proving who wrote it; `approval: sealed` proves it ([threat model](/terragucci/reference/threat-model/#policy-overrides)).

### Override records

| Place | Shows |
|---|---|
| the wave's report | `roots[].policy.override`: who, when, the rules, the reason, the plan digest; `policy.overridden` lists the roots |
| the pull request's plan note, and the wave's `note.md` | the override that stands for each denied root, or the command to write one; the plan job still fails the root |
| the estate page | the roots the newest apply waves applied under an override |

## The base branch decides

A pull request's plan is checked against the `policy` key and directory at the base branch, so editing, deleting or renaming them, or `terragucci.yml`, changes nothing until merged.

| At the base | Result |
|---|---|
| no `policy` key | the pull request's own policy applies |
| the key, but no directory, or an unreadable config | every planned root fails |
| commit missing from the checkout | the checkout's key: every root fails if it has one, else no policy runs |

A base `terragucci.ts` is folded to a value without running it.

### Finding the base branch

terragucci reads `origin/<branch>`, and the checkout needs that ref fetched. `TG_BASE` wins on every forge.

**GitHub**

`GITHUB_BASE_REF`

**GitLab**

`CI_MERGE_REQUEST_TARGET_BRANCH_NAME`

**Forgejo**

`GITHUB_BASE_REF`

## Tests and the apply check

### tf-check

`tf-check` runs `conftest verify` or `opa test` on the base branch's policy and fails on a failing test. A directory with no `*_test.rego` is skipped.

### tf-apply

`tf-apply` checks each wave's plans before gating them. A denied wave applies nothing and records no approval; with `override` set it records the denial for an [override](#overriding-a-denial), and a root an override stands for goes on to the gate. The policy comes from the default branch, or from `TG_BASE` when set.

### The engines

terragucci downloads a missing engine once per job and refuses one whose SHA-256 differs from the pinned one.

| Engine | Packages read | Pinned version | `tf-check` runs |
|---|---|---|---|
| `conftest` | every package, unless `namespace` names one | 0.71.0 | `conftest verify` |
| `opa` | `main`, or every package under `terraform.policies` with `input: hcp`, unless `namespace` names one | 1.21.1 | `opa test` |

Offline jobs need the engine installed; drift runs and provisional Terragrunt previews skip the check.

## HCP Terraform policy sets

With `input: hcp`, terragucci wraps each plan as HCP Terraform does, so the Rego of an HCP Terraform OPA policy set reads the paths it reads there:

```yaml
policy:
  engine: opa
  path: policies
  input: hcp
```

```rego
package terraform.policies.no_public_buckets

deny contains msg if {
  some rc in input.plan.resource_changes
  rc.type == "aws_s3_bucket_public_access_block"
  rc.change.after.block_public_acls == false
  msg := sprintf("%s must block public ACLs (workspace %s)", [rc.address, input.run.workspace.name])
}
```

### The run fields

`input.plan` is the plan; `input.run` holds what terragucci knows of the run, in HCP Terraform's field names:

| Field | Value |
|---|---|
| `run.workspace.name`, `run.workspace.working_directory` | the root's path in the repo |
| `run.organization.name` | the repo's owner, from `<host>/<owner>/<name>` |
| `run.project.name` | the repo's name |
| `run.commit_sha` | the commit planned |
| `run.speculative` | `true` in `tf-plan`, `false` in a `tf-apply` wave |
| `run.message` | `pull request <n>` for a pull request's plan, else empty |
| `run.is_destroy`, `run.refresh_only` | `false` |
| `run.refresh` | `true` |
| `run.replace_addrs`, `run.target_addrs`, `run.workspace.tags` | empty lists |
| `run.variables` | empty |
| `run.cost_estimate.prior_monthly_cost`, `proposed_monthly_cost`, `delta_monthly_cost` | with `cost` set, the root's monthly cost before, after and the change, as decimal strings |

### policies.hcl

With `engine: opa` and `input: hcp`, terragucci runs each policy in the set's `policies.hcl` as HCP Terraform does:

```hcl
policy "no_public_buckets" {
  query             = "data.terraform.policies.no_public_buckets.deny"
  enforcement_level = "mandatory"
}

policy "owner_tags" {
  query             = "data.terraform.policies.owner_tags.deny"
  enforcement_level = "advisory"
}
```

Mandatory messages fail the root, as does a missing or unmatched `query` or an unknown level; advisory ones, the default, warn.

`namespace` keeps only the policies whose query is in that package.

Without `policies.hcl`, opa runs each package under `terraform.policies` as a policy. conftest ignores the file and treats every policy as mandatory.

The pinned OPA reads Rego 1.0, so older policies need `if` and `contains`. terragucci does not run Sentinel or `tfpolicy` policies.

---

# Responses to pipeline events

Source: https://intentius.io/terragucci/reference/responses/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/reference/responses/.
Set `respond:` in terragucci.yml only for the events I name, run `npx terragucci config check`, and open a pull request.
Run `terragucci respond` in its default dry-run mode only, and show me what each response would do.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

Every event has a default response that needs no model. No response runs a coding agent; people approve, apply and merge.

| Event | Response (default) | Other choices |
|---|---|---|
| plan finished | the grouped summary as the pull-request note | none |
| wave refused | a root-by-root diff of the approved plan against the current one, naming the attributes that moved | `off` |
| apply failed | triage from a table of known provider errors, each with its likely fix | `off` |
| drift found | a pull request writing the live value where the root sets a literal, and import blocks for resources the state does not hold | `attribute`, which also names who changed each drifted attribute; `off` |
| tip raised | one small pull request per tip: pin a provider from its lock file, add a lock file, add a canary | `off` |
| format check failed | a `fmt` commit on the pull request's branch, on request | `off` |
| module published | release notes from conventional commits | `off` |
| rollout wave merged | with [`rollouts`](/terragucci/reference/config/) set, a scheduled job opens the next wave once the merged one applied | `off`, which leaves the job out |
| module changed with no conventional commit | none; `tf-publish` proposes a patch | `suggest`: a suggested bump in a release pull request, from the typed-decision service |
| pull request opened or updated | none | `check`: a typed decision flags a description that leaves out what the plan destroys or replaces |

## Settings

Set a response per event under `respond` in `terragucci.yml`; a key you leave out keeps its default.

```yaml
respond:
  drift: pull-request        # the default; attribute names who changed each attribute
  apply-failed: triage       # the default
  plan: summary
```

| Key | Takes | Default |
|---|---|---|
| `plan` | `summary` | `summary` |
| `wave-refused` | `diff`, `off` | `diff` |
| `apply-failed` | `triage`, `off` | `triage` |
| `drift` | `pull-request`, `attribute`, `off` | `pull-request` |
| `tips` | `pull-request`, `off` | `pull-request` |
| `fmt` | `commit`, `off` | `commit` |
| `publish` | `notes`, `off` | `notes` |
| `rollout` | `next-wave`, `off` | `next-wave` |
| `version-bump` | `suggest`, `off` | `off` |
| `description` | `off`, `check` | `off` |

## Commands

Each response is a command that dry-runs by default; `--mode apply` opens the pull request or pushes the commit.

```bash
terragucci respond plan --report terragucci-report
terragucci respond wave-refused --approved terragucci-report/approved --current terragucci-report/current --wave 2
terragucci respond apply-failed --log apply.log
terragucci respond drift --mode apply
terragucci respond drift --root envs/prod/orders --import aws_sqs_queue.extra=https://sqs.us-east-1.amazonaws.com/123456789012/extra --mode apply
terragucci respond tips --mode apply
terragucci respond tips --report terragucci-report --branch my-change --mode apply
terragucci respond fmt --branch my-change --mode apply
terragucci respond publish --module modules/network
terragucci respond version-bump --module modules/network --mode apply
terragucci respond rollout modules/network 1.4.0 --mode apply
terragucci respond rollout --mode apply
```

With no module, `respond rollout` finds the rollouts in flight from their pull requests' `terragucci/rollout/` branches and continues each. Without `rollouts` set, nothing opens the next wave until someone runs it.

| A rollout's newest wave | `respond rollout` |
|---|---|
| merged and applied | opens the next wave |
| merged, not yet applied | waits |
| still open | leaves it alone |
| closed without merging | leaves it alone |
| the last wave, merged | leaves it alone |

`--json` prints one envelope, as every other command does.

## Refused waves and failed applies

### Wave refused

An approval binds a wave's set digest, so a wave whose root plan changed after approval applies nothing. The diff reads `terragucci-report/approved` and `terragucci-report/current` and lists each root whose plan digest moved. Approve again only once the new plan is the one you want.

### Apply failed

Triage knows these provider error classes:

| Class | Matches | Likely fix |
|---|---|---|
| access denied | `AccessDenied`, `AccessDeniedException`, `UnauthorizedOperation` | grant the permission the message names to the apply role |
| quota | `VpcLimitExceeded`, `LimitExceeded`, `TooManyBuckets`, `ServiceQuotaExceededException` | raise the quota or remove unused resources |
| throttling | `Throttling`, `ThrottlingException`, `RequestLimitExceeded` | run again; lower `-parallelism` if it repeats |
| already exists | `EntityAlreadyExists`, `ResourceAlreadyExistsException`, `BucketAlreadyOwnedByYou`, `InvalidGroup.Duplicate`, `QueueAlreadyExists` | import it, or give it another name |
| dependency | `DependencyViolation`, `DeleteConflict`, `BucketNotEmpty` | remove what depends on it first |
| state lock | `Error acquiring the state lock` | wait; a person runs `force-unlock` if no run holds it |

The table covers AWS provider errors and Terraform's state lock message; any other provider's error is listed as unknown.

## Drift

A refresh-only plan finds the drift (a full plan on a [choudoufu](/terragucci/concepts/glossary/#choudoufu) root under live resource markers), and the pull request writes the live value where the root's own resource block holds a literal. Merging it accepts the outside change, so read it first.

Other changes are only reported:

| The value | Why it stays |
|---|---|
| set from a variable or an expression | the literal to change is elsewhere |
| set inside a module | the module serves other roots too |
| on a `count` or `for_each` instance | one literal sets every instance |
| never set in the root | it comes from a default |
| on a resource deleted outside Terraform | the next apply makes it again |

In a Terragrunt repo a unit's resources are in the module its `terraform.source` names, and what differs between units is their `inputs`. Where the module sets the drifted attribute to `var.<name>` and the unit's own `terragrunt.hcl` sets `<name>` to a literal in `inputs`, the pull request writes the live value there, so only that unit changes. A literal in the module is only reported, since every unit calling the module shares it. The same goes for a module from outside the repo. The drift job plans again only the units its report shows drifted. `--import` names a root's files, so it is refused in a Terragrunt repo.

Under [`synth`](/terragucci/guides/plan-cdk-terrain-stacks/#stack-edits) the roots are the app's output, so there is no literal to write: `respond.drift: pull-request` with a `drift` schedule is a config error, and `respond drift` refuses.

For a resource the state lacks, pass `--import <address>=<id>`. From Terraform `1.14.1`, a root with a `.tfquery.hcl` file gets imports from `terraform query`.

### Drift attribution

With `respond.drift: attribute`, each drifted attribute goes through three steps in order; the first to answer wins.

| Step | Source | Decides |
|---|---|---|
| 1 | a table of by-design writes: ECS task count, autoscaling and node group sizes, provisioned DynamoDB capacity, RDS minor upgrades, `aws:` tags | the write is expected |
| 2 | CloudTrail LookupEvents over 14 days, for `aws_` resources | the newest write Terraform did not make: a service principal is a controller, a user is a person |
| 3 | a typed decision, when `decide` is set | the attribute stays unattributed below the `choice` threshold; sensitive values are never shown |

### Reading the audit log

| Needs | Detail |
|---|---|
| the `aws` CLI, version 2 | the generated drift job installs it against a pinned SHA-256 unless it is on the path; a pipeline you write installs it the same way |
| `cloudtrail:LookupEvents` | on the job's role |
| the region | `audit_region`, else the CLI's |
| roots or Terragrunt units | `terragucci stage tf-drift` lists who changed each attribute in the drift issue, under its root or unit |
| `decide.token_env` | received on GitHub and Forgejo |

If step 2 cannot run, it says so and step 3 follows.

| Attributed to | In the drift pull request | Suggestion |
|---|---|---|
| a controller write | left out | add `lifecycle { ignore_changes = [...] }` to the resource |
| a provider default change | left out | pin the provider version that kept the old value, or set the attribute |
| a human edit | kept, with the actor when known | accept or revert it in the pull request |

Nothing here applies or merges.

## Pull request and release events

### Description check

When `respond.description: check` and a [`decide` block](/terragucci/reference/config/#the-decide-block) are set, the plan job asks the service whether the title and description fit the plan. The flag never blocks a merge and changes no gate.

| Outcome | The note | `intent.json` |
|---|---|---|
| a yes at or above the threshold | starts with a line naming the destroys and replacements the text omits | records the decision |
| anything else | unchanged | says why |

```bash
terragucci respond description --report terragucci-report --title "retag email" --description "Tags only." --mode apply
```

### Tips, fmt and release notes

| Tip | The pull request |
|---|---|
| a provider taken by a range | pins it in `required_providers` at the version the lock file holds, so the next plan changes nothing |
| a root with no lock file | adds one written by `providers lock`, with hashes for Linux and macOS on amd64 and arm64 unless `--platform` names others |
| no canary | adds `waves.canary` |
| a rename (`--report`) | adds a `moved` block for each resource the plan destroys and creates with the same configuration ([terragucci-moved](/terragucci/reference/tips/#terragucci-moved)), after the new block, in a pull request into `--branch` |

`tips --report` reads the plans of a `stage tf-plan` report and proposes only the `moved` blocks; run it in a checkout of the branch that renamed the resources, after its plan. The generated tips job runs on the default branch after the applies, without `--report`.

Under [`synth`](/terragucci/guides/plan-cdk-terrain-stacks/#stack-edits) the tips job runs the command first, and only the canary tip opens: the other two would edit files the command writes.

`fmt` runs on request and pushes one commit to the pull request's branch, and refuses the default branch. In a Terragrunt repo it runs `terragrunt hcl fmt` beside the binary's `fmt`, and the commit is `style: terragrunt hcl fmt` when only `.hcl` files moved. The generated pipeline's `fmt` job runs it after a failed check, so the check job holds no token that pushes.

Release notes cover the commits that touched a module between its last two tags, breaking changes first.

### Version bump

The bump comes from the [version bump rules](/terragucci/reference/stages/#version-bump-rules). Under `version-bump: suggest`, the typed-decision service picks the bump when no conventional commit landed since the last release; this needs [`decide`](/terragucci/reference/config/).

| Where | What |
|---|---|
| a module's releases | its git tags, `<module>/v1.2.0` |
| a registry-only project | pass `--since <ref>`; the `version` file at that ref is the last release (0.0.0 if none) |
| the `version-bump` job | runs `terragucci respond version-bump --mode apply` on the default branch after every apply wave, with full history; it needs permission to push a branch and open a pull request; a failed response never fails the job |
| the release pull request | writes the `version` file with the bump and its probability; merging confirms it and the next `tf-publish` publishes it |

## Runtime

Responses run in CI with no model. To hand a result to your own agent, run the command with `--json` in a job whose token can only comment, as in [Have an agent summarize a refused wave](/terragucci/guides/agent-refused-wave/). The agent never holds an apply role or a gate's signing key.

---

# Scale

Source: https://intentius.io/terragucci/reference/scale/

The bench operates about 10,000 resources in a dozen repos through the CI jobs terragucci generates. It uses no server and one modest runner.

The chart gives the CI time and runner minutes to expect at your estate's size.

The bench times operating an estate already split into 1,361 states. Building and splitting that estate is setup, before the clock starts. What makes it hard:

- Each state belongs to its own root, and roots read each other's state, so they apply in order, in waves.
- Each root planned or applied starts its own provider process, about 800 MB.
- The worst case is a change all of them take: a bump to a shared tags module.
- Plan notes and reports must fit the forge's [comment limit](/terragucci/reference/report/#comment-limits) and stay readable.

## Results

A run passes only when every phase succeeds and the state files hold every resource the estate declares. It runs on a local Forgejo against an AWS emulator.

## The run

Each timed phase starts at its first push or merge and ends when its last run does.

1. Setup: the bench builds the estate and pushes each repo with no pipeline.
2. Reconcile: `reconcile --mode apply` in the [control repo](/terragucci/concepts/control-repo/) opens a pipeline pull request in every repo it lists, and each is checked and planned.
3. Create: the bench merges them, and each repo's waves apply its platform root first, then the roots that read its state.
4. Plan: a pull request in each repo changes `modules/estate`, which every root calls, so each repo gets one plan note covering all its roots.
5. Change: the bench merges those, and the waves apply the new tags.
6. Verify: the state files must hold every resource.

## Limits

- `parallelism` is 4 in each repo's `terragucci.yml`: four roots at once, each with its own provider.
- The runner takes 3 jobs at once, so repos run side by side only that far.
- Each root commits `.terraform.lock.hcl`. Without lock files, `init` downloads the provider again each time: on the 301-resource estate a run took 24 minutes without them and 8 with them.
- The emulator answers at once. A cloud account adds API latency and throttling, and IAM's default quota of 1,000 roles is below the 1,496 this estate declares.

## Estate setup

The bench's own scripts build the estate. [choudoufu](/terragucci/concepts/glossary/#choudoufu)'s `terralith-gen` writes a terralith at a chosen scale: one root module of AWS resources. A script then carves it into roots and spreads them over repos.

| Root | Holds | Repo |
|---|---|---|
| Platform | the network, ECS cluster and Route 53 zone | platform |
| Service | one ECS service, its task definition and its IAM role | platform |
| DNS | ten Route 53 records | platform |
| Team | one team's IAM role and policies | the other repos, 100 a repo |
| `count` or module teams | two teams | the other repos, 100 a repo |

Service and DNS roots read the platform root's state. Sharing its repo lets its waves order them.

## Reproduce

The bench starts its own containers and calls no cloud. [CONTRIBUTING.md](https://github.com/INTENTIUS/terragucci/blob/main/CONTRIBUTING.md#the-scale-bench) says how to run it.

---

# State backends

Source: https://intentius.io/terragucci/reference/state-backends/

terragucci runs your binary for plan and apply, so every backend the binary supports plans and applies. Plans and drift runs take no state lock (`-lock=false`); a wave's plan and apply wait up to five minutes for it (`-lock-timeout=5m`). The commands below read or write the state themselves, so each supports the backends listed.

## By backend

| Backend | Version an apply records | [`state export`](/terragucci/guides/export-a-state-version/) | [`unlock-state`](/terragucci/guides/release-a-state-lock/) | [Migrations](/terragucci/reference/migration-files/) | [Ephemeral copies](/terragucci/guides/ephemeral-environments/) |
|---|---|---|---|---|---|
| `s3` | `x-amz-version-id`, with bucket versioning on | yes, with bucket versioning on | with `use_lockfile = true`; a DynamoDB-only lock is refused | with `use_lockfile = true` | yes |
| `gcs` | the object's generation, with object versioning on | yes, with object versioning on | yes: the lock object, by its generation | yes | yes |
| `azurerm` | `x-ms-version-id` with blob versioning, else a snapshot terragucci takes with `snapshot = true` | yes, with either | yes: the blob lease | yes | yes |
| `http`, GitLab-managed state | the serial | yes, by serial | with `lock_address` and `unlock_address` | no | yes |
| `http`, any other server | off | no | no | yes, through the binary | no |
| `pg` | off | no | no | yes, through the binary | no |
| `kubernetes` | off | no | no | yes, through the binary | no |
| `consul` | off | no | no | yes, through the binary | no |
| `local` | off | no | no: the lock goes with the process that took it | yes | yes |
| `remote`, or a `cloud` block | not read | no | no | a [backend move](/terragucci/reference/migration-files/) out of it only | no |

Off means the backend replaces the state on each write and keeps no history; the estate page says versions are off. Not read means the backend may keep versions that terragucci does not read.

"Through the binary" means the migration reads the state with `state pull` and writes it with `state push` under the backend's own lock. With no version id to bind, its approval binds the digest of each state's contents.

### Migrations

| Migration | Backends |
|---|---|
| a move or split between roots | `s3` with a lock file, `gcs`, `azurerm`, `local`, and through the binary `pg`, `kubernetes`, `consul` and `http` other than GitLab's |
| a backend move, to the backend the root's code names | the same |
| a backend move, from | the same, and a workspace over the TFE API (`remote` or `cloud`) or an exported state file (`file`) |

A root with a `cloud` block, and GitLab-managed state, take part in no migration. [Migration files](/terragucci/reference/migration-files/) has each kind.

## choudoufu record store

A [choudoufu](/terragucci/concepts/glossary/#choudoufu) root under live resource markers keeps its resources as records in a record store and has no state file.

| Command | With a record store |
|---|---|
| plan and apply | yes; two applies of one estate take no state lock ([with choudoufu](/terragucci/concepts/locking-and-staleness/#with-choudoufu)) |
| progress while a wave applies | read from an `s3` or `local` store; a `kubernetes` store is not read, and its resources show done when the root's apply returns ([Watch a choudoufu wave apply](/terragucci/guides/watch-a-choudoufu-wave/)) |
| record versions after an apply | listed with `choudoufu live-history` from an `s3` store; a `local` or `kubernetes` store keeps none |
| `unlock-state` | nothing to release: no state lock is held, and it runs no binary |
| `state export` | no; it reads a state backend |
| migrations | a move between estates retags the resources; a `backends` migration adopts a root on `s3` (with a lock file), `gcs`, `azurerm` or `local` state into an estate |

---

# Threat model

Source: https://intentius.io/terragucci/reference/threat-model/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/reference/threat-model/.
For this repo's forge, compare the branch protection, the merge methods and the apply role's trust policy with the page's "Branch protection" tab, reading them through the forge's API or CLI.
List each setting that differs and what it leaves open; do not change settings, tokens or trust policies yourself.
Do not run `terragucci override`.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

The pipeline runs as jobs in your CI, so its trust is your forge's.

## Trust

| Who | Trusted to | Kept in check by |
|---|---|---|
| Anyone with write access | run CI jobs, and the plan role through a pull request | the plan role is read-only; its trust names your repo |
| Reviewers | decide what reaches the default branch | branch protection |
| Approvers: under `approval: ledger` anyone who can push to `chant/lifecycle`, under `sealed` the people `.chant/allowed_signers` lists | release a gated wave | the plan digest the approval names, and under `sealed` its seal |
| Overriders: the people `policy.override` lists at base | let one denied plan of one root through `tf-apply` | the root, plan digest and rules the override names, and under `sealed` its seal |
| The default branch's pipeline | apply with the apply role | the apply role's trust, set to the default branch's subject alone |
| On GitLab, anyone allowed to run a pipeline on the default branch | start `mr-apply` with any variables | `mr-apply` reads the merge request, the note and the head from GitLab, and refuses a head the merge request does not have |
| The review command, with `review.agent` | read a change and write a note about it | no forge token and no cloud role in its step; the note approves nothing ([The review](#the-review)) |
| The drift agent's command, with `agent.drift` | edit files after the drift job opens the drift issue | no forge token and no cloud role in its step; its change comes back as a pull request, refused when it touches a guarded path, that plans and applies like any other |
| An agent connected to `terragucci mcp` | read the estate, reports, state versions, audit trail and DORA figures | the server's tools only read, and it holds the reports bucket's read credentials from its own environment, never from the agent |
| A fork's author | nothing | forks get no plan job and never apply |
| The [chat relay](#the-chat-relay), in your cloud | under `ledger` and `pr-review`, record an approval of a waiting digest in the name of a chat user the signers file lists | Slack's or Teams' signature on each request, the signers file on the default branch, the digest waiting, and an approve-only token |

## Job access

"Change" means code from a branch or a pull request that has not merged. A pull request or merge request from a branch of the repo runs the pipeline file as the change has it, so its author can edit any job that runs on it.

**GitHub**

| Job | Runs on | Code | Forge token | Cloud identity |
|---|---|---|---|---|
| `check` | a push to any branch; a fork's pull request | the pushed branch | none | none |
| `fmt` | a failed `check` of a push to a branch other than the default | the pushed branch's files, formatted, never run | `github.token`, `contents: write` | none |
| `plan` | a pull request from the repo | the change | `github.token`, `statuses: write`, only in the step before the checkout | plan role |
| `plan-note` | after `plan` | none of the change's; the plan job's note and status read as data | `github.token`: statuses and pull requests write | none |
| `replan` | `/terragucci plan` | the change's head, from the default branch's workflow | `github.token`: statuses and pull requests write, only in the step that reads the comment, before the head is checked out | plan role |
| `replan-note` | after `replan` | as `plan-note` | as `plan-note` | none |
| `apply-wave-<k>` | a push to the default branch | merged code | `github.token`, `contents: write` | apply role |
| `apply-wave-<k>-share-<s>` | with `waves.jobs`, after its wave's deciding job | merged code | `github.token`, `contents: write` | apply role |
| `apply-done` | with `waves.jobs`, after the last wave's share jobs | none | `github.token`, `statuses: write` | none |
| `apply-comment` | `/terragucci apply` | the merge commit; with `apply.when: pull-request`, the open change's head | `github.token`, `contents: write` | apply role |
| `pr-merge` | `apply.merge: auto` | none of the change's | the merge token | none |
| `pr-lock` | `pull_request_target` and lock comments, with `locks: plan` | none of the change's; its diff read as data, from the default branch's workflow | `github.token`, `contents: write`, statuses and pull requests write | none |
| `confirm` | a push, with `apply.when: pull-request` | merged code | contents read, statuses write | plan role |
| `approval` | a review of a pull request from the repo, with `approval: pr-review` | none of the change's; the head's plan note read as data | `github.token`: statuses write, pull requests read | none |
| `drift` | the `drift` schedule | the default branch | `contents: write`, issues | plan role |
| `tips` | a push to the default branch | merged code | `contents: write`, pull requests | none |
| `version-bump` | after the last apply, with `respond.version-bump: suggest` | merged code; it opens release pull requests | `github.token`, `contents: write`, pull requests; the `decide` key when set | none |
| `publish` | after the last apply, with `modules.publish` | merged code; it pushes module tags | `github.token`, `contents: write`; the registry secrets, and with `modules.attest` `COSIGN_PRIVATE_KEY` and `COSIGN_PASSWORD`, which no other job holds | none |
| `resume` | the resume schedule, with `apply.resume` | merged code: the default branch's commit | `github.token`, `contents: write` | apply role |
| `rollout` | the rollout schedule, with `rollouts:` | the default branch; it edits pins and opens pull requests, and runs none of their code | the `token_env` secret, else `github.token`; `contents: write`, pull requests | none |
| `agent` | `/terragucci agent` | the change's head, with no credentials in the checkout | the job's own, kept from the agent's step | none |
| `agent-push` | after `agent` | a patch, never run | the `agent.token_env` secret | none |
| `drift-agent` | after `drift` opens the drift issue, with `agent.drift` | the default branch, with no credentials in the checkout; the drift report as data in a prompt | `github.token`, `contents: read`, kept from the agent's step | none |
| `drift-agent-push` | after `drift-agent` | a patch, never run | the `agent.token_env` secret | none |
| `review` | `workflow_run` after the pipeline's run of a pull request from the repo, with `review.agent`; the review workflow is the default branch's | the change's diff, title and description, and its run's plan report, as data in a prompt; the command and the instructions from the default branch | `github.token`: contents, actions and pull requests read, kept from the command's step | none |
| `review-note` | after `review` | none of the change's; the review read as data | `github.token`, `pull-requests: write` | none |

| OIDC subject | Jobs |
|---|---|
| `repo:<owner>/<repo>:pull_request` | `plan` |
| the default branch's ref | every job a comment, a schedule or a push to the default branch starts |

**GitLab**

| Job | Runs on | Code | Forge token | Cloud identity |
|---|---|---|---|---|
| `check` | a push to any branch | the pushed branch | `GITLAB_TOKEN` and the job token, dropped before the branch's code runs; no `GITLAB_TOKEN` with `gitlab.token: protected` | none |
| `fmt` | a failed `check` on a branch other than the default; not with `gitlab.token: protected` | the branch's files, formatted, never run | `GITLAB_TOKEN` | none |
| `plan` | a merge request from the project | the change | `GITLAB_TOKEN`, `api` scope; none with `gitlab.token: protected` | plan role |
| `apply-wave-<k>` | a push to the default branch | merged code | `GITLAB_TOKEN` | apply role |
| `drift` | a pipeline schedule | the default branch | `GITLAB_TOKEN` | plan role |
| `tips` | a push to the default branch | merged code | `GITLAB_TOKEN` | none |
| `version-bump` | after the last apply, with `respond.version-bump: suggest` | merged code; it opens release merge requests | `GITLAB_TOKEN` | none |
| `publish` | after the last apply, with `modules.publish` | merged code; it pushes module tags | `GITLAB_TOKEN`; the registry variables, and with `modules.attest` `COSIGN_PRIVATE_KEY` and `COSIGN_PASSWORD`; GitLab hands project variables to every job, so mark them Protected and Masked | none |
| `resume` | the schedule with `TERRAGUCCI_SCHEDULE=resume`, with `apply.resume` | none; it retries the default branch's waiting apply job through the API | `GITLAB_TOKEN` | none |
| `rollout` | the schedule with `TERRAGUCCI_SCHEDULE=rollouts`, with `rollouts:` | the default branch; it edits pins and opens merge requests, and runs none of their code | `GITLAB_TOKEN` | none |
| `comments` | the comments schedule, with `comments:` set | the default branch; notes read as data, the author's role checked; with `gitlab.token: protected`, the plan job's note and status read as data | `GITLAB_TOKEN`, to reply, post plan notes, and start or retry pipelines; with `apply.when: pull-request` also the merge token | none |
| `mr-apply` | a default-branch pipeline `comments` starts, with `apply.when: pull-request` | the default branch's pipeline file, then the open change's head | `GITLAB_TOKEN` | apply role |
| `pr-merge` | after `mr-apply`, with `apply.merge: auto` | none of the change's, and none of `mr-apply`'s artifacts | the merge token | none |
| `confirm` | a push, with `apply.when: pull-request` | merged code | `GITLAB_TOKEN` | plan role |

| GitLab fact | What it means |
|---|---|
| no agent comment | no job pushes to a merge request's branch |
| a merge request's own pipeline never applies | with `apply.when: pull-request` the apply runs in a pipeline of the default branch, so its OIDC subject is the default branch's and the apply role keeps trusting that alone |
| the `comments` job starts that pipeline with the merge token | the one token that may run a pipeline on the protected default branch; protected and scoped to the `terragucci-merge` environment, which only `comments` and `pr-merge` name |
| the pipeline's variables name the merge request, the note and the head | they are pointers: `mr-apply` reads the note, its author's role, the merge request and its head from GitLab before any credential, and refuses a head that differs |
| by default a merge request's code runs with `GITLAB_TOKEN` | its author can edit any job in the merge request's pipeline, and the token acts as the project's bot: it posts notes and statuses and pushes branches, `chant/lifecycle` included, so under `approval: ledger` it can write an approval line |
| `gitlab: { token: protected }` | `GITLAB_TOKEN` is a protected variable, which no merge request or branch pipeline gets; the plan job writes its note and status into its report and stops if it sees the token, and the comments job posts them |
| a pipeline on any protected branch gets protected variables | with `gitlab.token: protected`, whoever may push to a protected branch, `chant/lifecycle` among them, can read the token there |
| the bot's approval never counts | under `approval: pr-review` and in `apply.requires`, an approval by the user the token acts as is the pipeline's, so it releases nothing |
| the OIDC subject carries the pipeline's branch | a merge request's plan job has its source branch, so the plan role trusts every branch |

**Forgejo**

| Job | Runs on | Code | Forge token | Cloud identity |
|---|---|---|---|---|
| `check` | a push to any branch; a fork's pull request | the pushed branch | the run's own, dropped from the step that runs the branch's code | none |
| `fmt` | a failed `check` of a push to a branch other than the default | the pushed branch's files, formatted, never run | the run's own | none |
| `plan` | a pull request from the repo | the change | the run's own, dropped from the step that runs the change's code | plan role |
| `plan-note` | after `plan` | none of the change's; the plan job's note and status read as data | the run's own | none |
| `replan` | `/terragucci plan` | the change's head, from the default branch's workflow | the run's own, dropped from the step that runs the change's code | plan role |
| `replan-note` | after `replan` | as `plan-note` | the run's own | none |
| `apply-wave-<k>` | a push to the default branch | merged code | the run's own | apply role |
| `apply-wave-<k>-share-<s>` | with `waves.jobs`, after its wave's deciding job | merged code | the run's own | apply role |
| `apply-done` | with `waves.jobs`, after the last wave's share jobs | none | the run's own | none |
| `apply-comment` | `/terragucci apply` | the merge commit; with `apply.when: pull-request`, the open change's head | the run's own | apply role |
| `pr-merge` | `apply.merge: auto` | none of the change's | the merge token, required | none |
| `pr-lock` | `pull_request_target` and lock comments, with `locks: plan` | none of the change's; its diff read as data, from the default branch's workflow | the run's own | none |
| `confirm` | a push, with `apply.when: pull-request` | merged code | the run's own | plan role |
| `approval` | a review of a pull request from the repo, with `approval: pr-review` | none of the change's; the head's plan note read as data | the run's own | none |
| `drift` | the `drift` schedule | the default branch | the run's own | plan role |
| `tips` | a push to the default branch | merged code | the run's own | none |
| `version-bump` | after the last apply, with `respond.version-bump: suggest` | merged code; it opens release pull requests | the run's own; the `decide` key when set | none |
| `publish` | after the last apply, with `modules.publish` | merged code; it pushes module tags | the run's own; the registry secrets, and with `modules.attest` `COSIGN_PRIVATE_KEY` and `COSIGN_PASSWORD`, which no other job holds | none |
| `resume` | the resume schedule, with `apply.resume` | merged code: the default branch's commit | the run's own | apply role |
| `rollout` | the rollout schedule, with `rollouts:` | the default branch; it edits pins and opens pull requests, and runs none of their code | the `token_env` secret, else the run's own | none |
| `agent` | `/terragucci agent` | the change's head, with no credentials in the checkout | the run's own, kept from the agent's step | none |
| `agent-push` | after `agent` | a patch, never run | the `agent.token_env` secret | none |
| `drift-agent` | after `drift` opens the drift issue, with `agent.drift` | the default branch, with no credentials in the checkout; the drift report as data in a prompt | the run's own, kept from the agent's step | none |
| `drift-agent-push` | after `drift-agent` | a patch, never run | the `agent.token_env` secret | none |
| `review` | `pull_request_target` of a pull request from the repo, with `review.agent`; the review workflow is the base branch's | the change's diff, title and description, and its run's plan report, as data in a prompt; the command and the instructions from the default branch | the run's own, which can write, kept from the command's step | none |
| `review-note` | after `review` | none of the change's; the review read as data | the run's own | none |

Forgejo sets the run token's scope itself; a job with a cloud role asks only for `id-token: write`, with `enable-openid-connect: true`. `plan`'s OIDC subject ends in `:pull_request`; the rest use the default branch's ref.

With `reports.bucket` set and no `reports.role`, the bucket keys also reach `plan`, `replan` and `drift` ([Credentials](/terragucci/reference/pipeline/#credentials)).

## State access per environment

Whatever root a job runs, its role reaches every state the role's IAM policy grants. One `plan_role` and one `apply_role` means every root runs as the same pair: a dev root's plan can read prod's state and a dev apply can write it.

With [`oidc.roles`](/terragucci/reference/pipeline/#credentials) (or `terragrunt.credentials` for units), each root runs with the pair of the first glob it matches. Grant each pair only its own environment's state keys. Then nothing a root runs (init, plan, apply or a step) holds an identity that reaches another environment's state. A mistake in one environment's code, or a backend pointed at the wrong key, is refused by the cloud.

| Guard | Covers | Does not cover |
|---|---|---|
| a pair per environment, scoped to its state keys | a root reading or writing another environment's state with the identity it runs as | code that reads the job's token file and assumes another environment's role itself: one job's token is good for every role whose trust names the job's subject, so the subject separates plan from apply, not environments |
| `config check` | warns when one role is two environments' role, when a root reads another environment's state through `terraform_remote_state` (its roles must reach that state), and when a root is left with no role; lists each role's roots and the state keys it needs | the IAM policy itself: `config check` reads the roots' code, never the cloud, so a policy wider than the keys it lists goes unseen |
| state contents never in the reports bucket | reports, `states.json`, `edges.json` and the estate page hold version ids and root paths only | a provider or step that prints state values into a job log |

### Exporting a state

[`terragucci state export`](/terragucci/guides/export-a-state-version/) downloads one version of a root's state to the machine of whoever runs it, and nowhere else.

| Guard | Stops | Does not stop |
|---|---|---|
| a request on `chant/lifecycle`, and an approval of its digest by someone other than the requester | an export nobody else agreed to, through terragucci | someone whose own identity reads the bucket downloading the object with the cloud's CLI; scope who holds such an identity |
| under `approval: sealed`, the approval's seal | a forged approval line | a listed approver's stolen key |
| the record in `_gates/tf-state-export/done.jsonl`, written before the file | an export the audit trail does not name | a requester name chosen by the person running it: under `ledger` it is git's `user.name` or `--actor` |
| no job artifact, no bucket copy | the state reaching everyone with read access to the repo, or the bucket's readers | the requester's own copy once written |

## Approval modes

The gate policy decides when a wave waits: `always`, `on-destructive` (the default) or `never`. When it waits, the `approval` key in `terragucci.yml` at base decides which approvals count; with no key, [`chant.workspace.json`](/terragucci/concepts/glossary/#chantworkspacejson) at base does. Base is the applied commit's first parent.

| Mode | Set by | An approval counts when | Stops | Does not stop |
|---|---|---|---|---|
| No gate | `gate: never` | no wave waits | nothing past review and branch protection | any merged change applying |
| `ledger`, the default | `approval: ledger` at base, or no key and no gate under [`identity.gates`](/terragucci/concepts/glossary/#identitygates) | a line on [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle) approves the wave's set digest, newer than its pending fact | a wave whose plans moved after approval | anyone who can push to `chant/lifecycle` writing that line: every writer, and the apply jobs' token; on GitLab without `gitlab.token: protected`, a merge request's code through that token |
| `pr-review` | `approval: pr-review` at base | as under `ledger`, or the merged pull request's head was approved by a writer other than its author (on GitLab, an approval by a Developer or higher after the merge request's latest push) and the wave plans the digest its plan note recorded | as under `ledger`, a review standing for plans that moved after it, and an approval by the pipeline token's own user | as under `ledger`; anyone who can edit the plan note's comment can change the digest it records |
| `sealed` | `approval: sealed` at base, or no key and `identity.gates` listing gates at base; then every wave gate needs a seal | as above, and [`terragucci approve --sign`](/terragucci/reference/cli/#approve) sealed it with a key the signers file at base lists for that approver | forged lines from writers and job tokens; a change editing the `approval` key, the signers file, `.chant/trust.json` or `chant.workspace.json` to pass itself; signed fields edited later; moved plans | a listed approver's stolen key; an approver releasing their own change; a rebase merge of several commits, whose base is the change's own commit |

A wave about to apply under an approval marks it used in `_gates/tf-apply/applied.jsonl` on `chant/lifecycle`. A used approval of other plans makes the wave wait (exit 3) where it would refuse (exit 4); it approves nothing, so a forged line there releases no wave.

No approval counts when sealing is on and base has no signers file. A reviewed change that sets `approval: ledger`, or with no key empties `identity.gates`, turns sealing off for the merges after it. [Which commit the rule is read from](/terragucci/guides/approve-a-wave/#rule-commit).

## Policy overrides

An override lets `tf-apply` apply one root's denied plan. It never edits the policy, and `tf-plan` still fails the root. `policy.override` in the config at base lists who may write one; with no key there, no override counts ([steps](/terragucci/reference/policy/#overriding-a-denial)).

| Mode | An override counts when | Stops | Does not stop |
|---|---|---|---|
| `ledger` or `pr-review` | a line on `chant/lifecycle` names the root, its plan digest and the rules that denied it, is newer than the recorded denial, gives a reason, and names someone listed at base | a change adding its author to `policy.override` to pass itself; an override standing for a plan or rules that changed; a line by someone unlisted; a line a job recorded (`via`) | anyone who can push to `chant/lifecycle` writing that line in a listed name, the apply jobs' token included |
| `sealed` | as above, and sealed by a key the signers file at base lists for that person | as above, and forged lines from writers and job tokens | a listed person's stolen key; a listed person overriding their own change |

No generated job runs `terragucci override` or writes an override line: the wave records the denial, and before it applies under an override it marks that override used in `_gates/policy-override/applied.jsonl`. A used override of another plan makes the wave record the new denial and exit 1 where it would exit 4; it lets nothing through, so a forged line there applies nothing. A root the policy could not check is never overridden.

## Apply before merge

With `apply.when: pull-request`, the open change's head runs with the apply role. The reviewer who approves the head is the guard. On GitLab the `comments` job runs the checks, and `mr-apply` runs them again.

| Check before any credential | Stops |
|---|---|
| Forks never apply | outside code meeting the apply role |
| A reviewer other than the author approved the head; no reviewer's last review asks for changes (on GitLab, an approval after the latest push) | unreviewed code meeting the apply role |
| On GitLab, the head the pipeline's variable names is the merge request's head now | a pipeline started by hand for code nobody approved |
| The head did not move while the comment was read, and contains the default branch as it is now | applying code nobody reviewed, or undoing merged changes |
| The change does not edit the pipeline file | a change rewriting the job that applies it |
| Waves, gate, signers, policy, config and `steps` come from the default branch | a change loosening its own gate, or adding a step that runs with the apply role |
| No other open pull request holds a lock on its roots | two changes applying the same root |

After the checks the change's providers, modules and external data sources run with the apply role and the job's `contents: write` token; review them before approving the head ([what they can reach](/terragucci/reference/pipeline/#pull-request-code-access)).

## The chat relay

[`terragucci relay`](/terragucci/guides/approve-from-chat/) turns a Slack click or a Teams reply into an approval line on `chant/lifecycle`. It runs in your cloud, and terragucci hosts no part of it.

| Guard | Stops |
|---|---|
| Each request is verified: Slack's signing secret over the timestamp and the body, within five minutes; the Teams outgoing webhook's HMAC over the body | anyone else posting a click, and a Slack click replayed later |
| The chat user maps to a principal only through their line of the signers file on the default branch, which a reviewed merge changes | an unlisted chat user approving, and a pull request adding its author's chat id to pass its own wave |
| The approval names the digest the message showed, and only a wave waiting for that digest takes it | a click approving plans that moved after the message |
| Under `approval: sealed` the relay records nothing | a relay, or whoever holds its token, releasing a sealed gate |
| The token is approve-only: the relay refuses one that administers the repo or may push to the default branch, and on GitLab one with the `api` scope; it uses the token only to fetch the repo and push `chant/lifecycle`, and starts no job | a stolen relay token merging, applying or changing settings |
| The answer goes to Slack's own `response_url` hosts only | the relay posting to an address a request names |

| It does not stop | Because |
|---|---|
| A stolen chat account approving as its owner | the chat platform's login is the identity the relay checks |
| Whoever holds the relay's token or its secrets writing approval lines in any listed name | under `ledger` and `pr-review` an approval line is the relay's word, as any writer's is; `sealed` does not count them |
| A Teams reply replayed while the same digest still waits | Teams signs the body with no timestamp; the replay approves only that digest, in the same person's name |
| A Slack retry within five minutes | the second click finds the wave approved and records nothing |

The relay's token pushes `chant/lifecycle` like any approver's, so it is one more writer the [approval modes](#approval-modes) account for.

## Steps

[`steps`](/terragucci/guides/run-steps/) are commands the stage runs in the plan, apply and drift jobs, with the job's cloud identity (the apply role on an apply wave) and without its forge tokens. The stage reads them from `terragucci.yml` at base only.

| Run | Steps read at | So a change cannot |
|---|---|---|
| a pull request's plan | the target branch | run a step it adds with the plan role, or skip one it removes |
| an apply after a merge | the applied commit's first parent, as the approval mode | run a step it adds with the apply role on its own merge, or drop an `on_failure: approve` step to pass its own gate |
| `apply.when: pull-request` | the base the head applies onto | run a step it adds with the apply role before it merges |
| drift | the default branch's checkout | (drift runs no change) |

If the base's file cannot be read, the stage fails when the checkout names steps and runs none otherwise; it never runs the change's. An edit to `steps` takes effect for the changes after it merges.

This does not stop a step from running whatever its command runs at the time: a step that calls a script in the repo runs the change's copy. Keep what a step runs out of the roots a change can edit, or call a pinned tool. A change can still run code with the plan role through its providers, modules and external data sources, as without steps. An `on_failure: approve` step holds a wave at the same gate as the gate policy, so the [approval mode](#approval-modes) decides who can release it.

## The review

The review command reads text the change's author wrote: the title, the description and the diff. A model can follow an instruction hidden in them.

| Guard | What it stops |
|---|---|
| the review jobs are a workflow of their own, which the forge runs from the default branch: GitHub on `workflow_run`, Forgejo on `pull_request_target`; the head is checked out without credentials and nothing in it runs | a pull request editing the review jobs it gets |
| the command's step holds the model's key and no forge token: the step clears the runner's token variables, and on GitHub the job's token only reads | the model posting, pushing or approving anything itself |
| neither review job has a cloud role | the model reaching the cloud through the pipeline |
| the instructions are read from the default branch with `git show`, and the command runs in the default branch's files | a pull request rewriting what the model is told, or the script the command names |
| `review-note` posts one issue comment, with every HTML comment in the review turned into text | a review that approves, or that carries a marker another job reads, such as the plan note's waves |
| `input.review` is read from the `terragucci-review-<head>` artifact only when the forge says a run of the default branch's review workflow kept it: on GitHub a `workflow_run` run of `terragucci-review.yml`; on Forgejo a `pull_request_target` run of it whose event names the default branch as base and the merged pull request and head. The artifact must also say it reviewed that pull request and head against the default branch | an artifact of the same name kept by any other run, the pull request's own pipeline or its edited copy of the review workflow included; a review of the head against another base |
| no note is read for `input.review` | a note, posted by any user or by any run's token (another branch's run included), setting the risk a policy reads |

A hidden instruction can still steer the note, such as risk `low` for a risky change. The note informs reviewers and never approves. A policy on `input.review.risk` holds back what the model flags and cannot vouch for what the model misses. The plan note and policy results in the prompt come from the plan job of the pull request's own run, which the pull request can edit so it shows a plan it does not make, as for every job in [Job access](#job-access). Git itself supplies the review job's diff, so such an edit shows in what the model reads and in the merged head's diff, where reviewers see it. On Forgejo the review waits up to 30 minutes for that plan before reviewing without it. Anything posted with the pipeline's token from any run changes what people read on the pull request and leaves the policy's input alone.

The review job keeps the verdict as the command's output plus the pull request, head and base that the previous step wrote. A review command that runs tools could rewrite them in the job; the default command runs no tools.

Forgejo runs a `pull_request_target` workflow from the pull request's base, which may be a branch other than the default. A writer who opens a pull request against a branch whose review workflow they edited gets a run of that copy; its artifact is passed over, since the run's event names another base. There is no `workflow_run` on Forgejo.

A Forgejo `pull_request_target` run's token can write, and the runner gives it to every step of the `review` job but the command's. Only a command that runs tools and leaves a process behind could read it, in the step that keeps the review ([Token scrub limits](#token-scrub-limits)).

## Token scrub limits

terragucci starts the binary, Terragrunt and the policy engine with every forge token removed by name and by value ([the list](/terragucci/reference/environment/#forge-tokens)). On GitHub and Forgejo, jobs that run a pull request's code also keep the token from the steps that run it ([which steps](/terragucci/reference/environment/#jobs-that-run-a-pull-requests-code)). Elsewhere a change's code can still reach one.

| Where | Forge token reachable |
|---|---|
| The binary, Terragrunt and the policy engine, started by `terragucci stage`, `respond`, `check-root` and `check-policy` | no; a `TF_` variable passes as set, even holding a token |
| On GitHub and Forgejo, the steps of `check`, `plan` and `replan` that run the change's code, their parent processes and their checkout's git config | no |
| On GitHub, a process the change's code leaves running in the `check`, `plan` or `replan` job's container | no API token: the later steps hold only `ACTIONS_RUNTIME_TOKEN`, which the artifact upload uses |
| On Forgejo, a process the change's code leaves running in the `check`, `plan` or `replan` job's container | yes: Forgejo's runner gives the run's token to every later step of the job, such as the one that keeps the report |
| GitLab's `check` job | no variable once its script starts; the runner's job token stays in the checkout's remote |
| GitLab's `plan` job | yes: `GITLAB_TOKEN`, `api` scope, and the job token in the checkout's remote; with `gitlab.token: protected`, only the job token |
| `apply-comment` and `mr-apply` with `apply.when: pull-request` | yes: the job's token, in the job's environment and the checkout, which the stage pushes the locks and the gate's records with |
| The jobs that run merged code: the apply waves and their share jobs, `confirm`, `drift`, `tips`, `version-bump`, `publish`, `resume`, `rollout` | yes: the job's token, and in `publish` the registry and signing secrets; the code there was reviewed and merged, and `rollout` runs none of the pull requests it opens |
| A change that edits its own pipeline file | whatever that pipeline asks for |

Each of these is a writer's own code in a job the forge gives a token to; branch protection keeps that token from reaching the default branch.

## Branch protection

**GitHub**

| Where | Setting | Relied on for |
|---|---|---|
| Default branch | Require a pull request, with one approval | every push there applies; `contents: write` tokens can push |
| Default branch | Dismiss stale approvals when new commits are pushed | the reviewed code is the merged code |
| Default branch | Require the `terragucci/plan` status | only planned changes merge |
| Default branch | Block force pushes and deletion | base, the first parent, stays the reviewed history |
| Repo settings | Allow merge commits or squash; turn off rebase merging | a rebase of several commits makes base the change's own commit |
| `chant/lifecycle` | A ruleset blocking force pushes and deletion, with pull requests and status checks off | approval history stays; approvers and jobs push records |
| Apply role | Trust only `repo:<owner>/<repo>:ref:refs/heads/<default branch>` | no branch or pull request assumes it |

**GitLab**

| Where | Setting | Relied on for |
|---|---|---|
| Default branch | Protected: push allowed to no one, merge to the role that reviews, force push off | every push there applies |
| Merge requests | Pipelines must succeed | only planned changes merge |
| Merge requests | An approval rule requiring one approval, with approval by the author prevented (GitLab Premium and Ultimate) | a second person reads each change |
| Merge requests | Merge commit; with fast-forward merges, squash commits set to Require | a fast-forward of several commits makes base the change's own commit |
| `chant/lifecycle` | Protected: push and merge for a role your approvers and `GITLAB_TOKEN` both hold, force push off | approval history stays |
| `apply.merge_token_env` variable | Protected, masked, environment scope `terragucci-merge`; a token whose role may merge into the default branch | only `comments` and `pr-merge` read it, and neither runs a change's code |
| `GITLAB_TOKEN` variable, with `gitlab.token: protected` | Protected and masked | no merge request or branch pipeline reads it |
| Apply role | Trust only `project_path:<group>/<project>:ref_type:branch:ref:<default branch>`, never `ref:*` | no branch assumes it |

By default `GITLAB_TOKEN` reaches every branch's pipeline, so give it a role no wider than posting notes and statuses and pushing `chant/lifecycle` need. `gitlab.token: protected` keeps it to protected branches.

**Forgejo**

| Where | Setting | Relied on for |
|---|---|---|
| Default branch | A protection rule: push disabled, one required approval, stale approvals dismissed, merge blocked on rejected reviews | every push there applies |
| Default branch | Status checks required: `terragucci/plan` | only planned changes merge |
| Default branch | Force push off | base stays the reviewed history |
| Repo settings | Merge commits or squash; rebase off | a rebase of several commits makes base the change's own commit |
| `chant/lifecycle` | A rule with push for everyone with write access and force push off | approval history stays; approvers and jobs push records |
| Apply role | Trust only `repo:<owner>-<owner id>/<repo>-<repo id>:ref:refs/heads/<default branch>` | no branch or pull request assumes it |
| `apply.merge: auto` | `merge_token_env` holds a token of a user who may push to the default branch | Forgejo refuses a merge with the run's own token |

## Next

- [The generated pipeline](/terragucci/reference/pipeline/) has each job and check in full.
- [Approvals runbook](/terragucci/guides/approvals-runbook/) for the day-to-day approval commands.
- [Access and identity](/terragucci/standards/access-and-identity/) maps each action to the forge, approval mode or cloud role that decides it.

---

# Tips

Source: https://intentius.io/terragucci/reference/tips/

Each tip shows in the [plan report](/terragucci/reference/report/#tips) and its pull request note, and in the `terragucci reconcile` dry run; `tips: false` turns them off.

They only advise. None fails a run or changes a gate, and no digest includes one.

Code tips read the HCL itself. Those and the [shared-module tip](#terragucci-shared-module) need `npm i -D @cdktn/hcl2json`; without it the job log says they were left out.

## Code tips

| Rule | The tip |
|---|---|
| [TF002](https://intentius.io/chant/lexicons/terraform/lint-rules/#tf002) | a provider with no version in `required_providers` |
| [TF003](https://intentius.io/chant/lexicons/terraform/lint-rules/#tf003) | no `required_version` |
| [TF004](https://intentius.io/chant/lexicons/terraform/lint-rules/#tf004) | a registry module with no `version` |
| [TF005](https://intentius.io/chant/lexicons/terraform/lint-rules/#tf005) | a git module with no fixed `?ref=` |
| [TF038](https://intentius.io/chant/lexicons/terraform/lint-rules/#tf038) | an `oci://` module with no tag, or the `latest` tag |
| [TF039](https://intentius.io/chant/lexicons/terraform/lint-rules/#tf039) | a registry module with a version range |
| [TF040](https://intentius.io/chant/lexicons/terraform/lint-rules/#tf040) | no committed `.terraform.lock.hcl` |
| [TF041](https://intentius.io/chant/lexicons/terraform/lint-rules/#tf041) | a Terragrunt `dependency` with `mock_outputs` whose allowed commands include `apply` or are not set |
| [TF042](https://intentius.io/chant/lexicons/terraform/lint-rules/#tf042) | a Terragrunt `dependency` that sets `skip_outputs` with `mock_outputs`, so every run reads the mocks |
| [TF043](https://intentius.io/chant/lexicons/terraform/lint-rules/#tf043) | a Terragrunt `terraform.source` with no version (a git ref, a `tfr` version or an `oci` tag) |
| [TF044](https://intentius.io/chant/lexicons/terraform/lint-rules/#tf044) | a Terragrunt config that keeps its state in a local backend |

## Rollout tips

### terragucci-shared-module

Ten or more roots include a local module. Publish it with `tf-publish` and pin it, so `tf-rollout` moves only the pinned roots, in waves.

### terragucci-floating-range

A module call is pinned to a range such as `~> 1.4`, which a rollout cannot move. Pin one version.

It also covers a provider range in `required_providers`, which `tf-rollout --provider` cannot cross. When TF038 or TF039 names the call, only that tip is given.

### terragucci-no-canary

A project has more than five roots and no `waves.canary`.

### terragucci-ungated-destroy

`gate` is `never` and a plan destroys or replaces something. Use `gate: on-destructive`.

### terragucci-many-roots

A hundred or more roots are planned on every change. Publish and pin shared modules.

## Plan tips

Plan tips read a root's plan and show only in the plan report and its note.

### terragucci-moved

A plan destroys one resource and creates another of the same type and provider, both in the root module and neither with a `count` or `for_each` key, and every value the create knows before apply equals the destroyed resource's: the block was renamed. Adding a `moved` block makes the plan move it instead. `terragucci respond tips --report <dir> --branch <branch> --mode apply` opens a pull request into the branch that adds it ([Responses](/terragucci/reference/responses/#tips-fmt-and-release-notes)).

Values known only after apply, and sensitive ones, are not compared. No tip is given when a destroy matches more than one create, or a create more than one destroy.

---

# Changes in 0.4.7

Source: https://intentius.io/terragucci/reference/whats-new/

Release `0.4.7` is on npm as `@intentius/terragucci@0.4.7`, and its [GitHub release](https://github.com/INTENTIUS/terragucci/releases/tag/v0.4.7) lists every change.

| To upgrade | Run |
|---|---|
| Each repo | `npx @intentius/terragucci@0.4.7 init`, then merge the pipeline it writes |
| Each approver | `terragucci approve` where you ran [`chant approve`](/terragucci/concepts/glossary/#chant); installing terragucci is enough ([approve](/terragucci/reference/cli/#approve)) |

## In 0.4.7

| What | Where |
|---|---|
| A wave refused because its plans moved after the approval names the `terragucci approve` command for the new plans | [Fix a refused wave](/terragucci/guides/fix-a-refused-wave/) |

## In 0.4.6

| What | Where |
|---|---|
| Approvals are one command, `terragucci approve`, for waves, migrations, state exports, lock releases and pull request environments, and every printed hint names it | [approve](/terragucci/reference/cli/#approve) |
| The choudoufu image runs choudoufu 0.25.0. Resource history lists each choudoufu record's past versions, and the estate page shows the count | [Change history](/terragucci/guides/see-every-project/#change-history) |

## From 0.4.5

0.4.6 carries every change of 0.4.5, listed by area below. Upgrading from 0.4.4 or earlier, also note:

| From 0.4.4 | Run |
|---|---|
| A Terragrunt repo that uses `generate` | `terragucci generate` again, so each unit's state key reads the ephemeral suffix ([In a Terragrunt repo](/terragucci/guides/generate-root-files/#in-a-terragrunt-repo)) |

- Changed default: a pull request that changes a Terragrunt unit also previews the units that depend on it, provisional and outside every digest. Set `terragrunt.dependents: follow` to keep the old behavior ([The terragrunt block](/terragucci/reference/config/#the-terragrunt-block)).
- Applies now run per root. With stock binaries, two overlapping pushes to one root can fail the newer apply with "Saved plan is stale"; run it again and it plans again ([Two applies of one estate](/terragucci/concepts/locking-and-staleness/#two-applies-of-one-estate)).

## Applies and locking

| What | Where |
|---|---|
| Pushes that change different roots apply at the same time; a root's own applies take turns at its state lock, and a superseded push stands down | [Applies side by side](/terragucci/reference/pipeline/#applies-side-by-side) |
| With [choudoufu](/terragucci/concepts/glossary/#choudoufu), a wave waits only for a run changing one of its own resources | [Two applies of one estate](/terragucci/concepts/locking-and-staleness/#two-applies-of-one-estate) |
| The choudoufu image runs choudoufu 0.24.0: a killed apply leaves records for the resources it finished | [Stock and choudoufu](/terragucci/concepts/locking-and-staleness/#stock-and-choudoufu) |
| One page for every lock layer, from the backend's state lock to choudoufu, with the claims behind each by repo shape and forge | [Locking and staleness](/terragucci/concepts/locking-and-staleness/) |
| A gated choudoufu wave whose approved apply was killed or failed applies the rest under the same approval, and the resume job finds a killed one | [Stopped applies](/terragucci/reference/pipeline/#stopped-applies) |
| A choudoufu wave's run view shows each resource done, in flight or waiting while it applies, read from the estate's records | [Progress](/terragucci/concepts/waves-and-approvals/#progress) |

## Plans and waves

| What | Where |
|---|---|
| `waves.after` orders plain roots that no `terraform_remote_state` read links | [Root order](/terragucci/reference/config/#root-order) |
| The plan note's blast radius lists each changed resource and the resources that depend on it, in its root and in roots that read an output it reaches | [Resources in the radius](/terragucci/concepts/waves-and-approvals/#resources-in-the-radius) |
| Every backend type gets a state address (local, pg, http, consul, kubernetes, remote), and `config check` names a read it cannot resolve | [State addresses](/terragucci/guides/track-cross-state-edges/#state-addresses) |
| `ephemeral` gives each open pull request its own copy of the roots you name, behind a gate, destroyed after a TTL; Terragrunt units and synthesized roots too | [Ephemeral environments](/terragucci/guides/ephemeral-environments/) |
| `apply.branches` maps a branch to root or unit globs, and a push there applies those alone behind the gate; drift plans them from their branch | [Apply from other branches](/terragucci/reference/config/#apply-from-other-branches) |
| A re-plan started by `workflow_dispatch`, with a pull request and an optional root | [Re-plans by dispatch](/terragucci/guides/re-plan-from-a-comment/#re-plans-by-dispatch) |

## State

| What | Where |
|---|---|
| `oidc.roles` gives each environment's roots their own plan and apply roles, and `config check` warns when one role serves two | [Keep each environment's roles to its own state](/terragucci/guides/scope-state-access/) |
| `terragucci state export` downloads a state version locally, after a second person approves, with an audit entry | [Export a state version](/terragucci/guides/export-a-state-version/) |
| The estate page marks each cross-state read `stale`, `current` or `unknown` against the producer's last apply | [Cross-state edges](/terragucci/guides/see-every-project/#cross-state-edges) |
| GitLab-managed state: each apply records its serial, and `state export`, `unlock-state` and ephemeral copies work on it | [GitLab-managed state](/terragucci/reference/pipeline/#gitlab-managed-state) |
| gcs and azurerm roots get state versions, `state export`, `unlock-state` and migrations, and `oidc.gcp.roles` and `oidc.azure.roles` give each environment its own identity | [GCP and Azure](/terragucci/guides/scope-state-access/#gcp-and-azure) |
| A backend move reads an HCP Terraform, Scalr or OTF workspace over the TFE API, or an exported state file | [Workspaces](/terragucci/reference/migration-files/#workspaces) |
| With choudoufu, which keeps per-resource state with no database to run, migration files retag resources between roots and adopt a root from a state file | [Estates](/terragucci/guides/move-resources-between-roots/#estates) |
| Migrations move state to and from `pg`, `kubernetes`, `consul` and `http` backends, which keep no versions | [Unversioned backends](/terragucci/reference/migration-files/#unversioned-backends) |

## Repo shapes

| What | Where |
|---|---|
| Terragrunt units get cost, steps, `waves.jobs`, drift pull requests and attribution, migrations, per-unit version pins, `generate` and state export | [Differences](/terragucci/guides/use-terragrunt/#differences) |
| A Terragrunt pull request plans each later layer on the earlier layers' planned outputs, never on `mock_outputs` | [Later layers](/terragucci/guides/use-terragrunt/#later-layers) |
| Units a `terragrunt.stack.hcl` generates go through every stage | [Explicit stacks](/terragucci/guides/use-terragrunt/#explicit-stacks) |
| `generate.disable_init: false`, and the apply job has Terragrunt create the state bucket | [Bucket bootstrap](/terragucci/guides/generate-root-files/#bucket-bootstrap) |
| Atmos instances as roots, in waves from `dependencies.components`, with roles by stack | [Use Atmos](/terragucci/guides/use-atmos/) |
| Terramate stacks as roots, in waves from `after` and `before`, with outputs sharing; stale generated code fails the job | [Use Terramate](/terragucci/guides/use-terramate/) |

## Binaries

| What | Where |
|---|---|
| Terraform and choudoufu pass the core claims OpenTofu passes | [Validation](/terragucci/reference/validation/) |
| Drift on a choudoufu root under live resource markers, from a normal plan | [Live roots](/terragucci/guides/turn-on-drift-checks/#live-roots) |

## Agents and review

| What | Where |
|---|---|
| `terragucci mcp`, a read-only MCP server over what the runs wrote | [Read the estate over MCP](/terragucci/guides/agent-read-over-mcp/) |
| `agent.drift` opens a pull request that fixes drift | [Have an agent fix drift](/terragucci/guides/agent-fix-drift/) |
| The AI review runs from the default branch's workflow, so a pull request cannot change the review it gets | [The review](/terragucci/reference/threat-model/#the-review) |
| GitLab gets the agent comment, the AI review and `waves.jobs` | [The agent comment](/terragucci/reference/pipeline/#the-agent-comment) |

## Your setup

| What | Where |
|---|---|
| `runner` picks each stage's runner: `runs-on` on GitHub and Forgejo, `tags` on GitLab | [Self-hosted runners](/terragucci/guides/add-to-a-repo/#self-hosted-runners) |
| `pass` hands named CI secrets and variables to the jobs that plan, apply and check drift | [Secrets and variables](/terragucci/reference/config/#secrets-and-variables) |
| A JSON Schema for `terragucci.yml`, for `config check` and your editor | [Schema](/terragucci/reference/config/#schema) |
| `own_jobs` keeps your own jobs in the pipeline across `init` runs | [Jobs of your own](/terragucci/reference/config/#jobs-of-your-own) |
| A Terraform and OpenTofu provider manages the [control repo](/terragucci/concepts/control-repo/)'s projects and defaults | [Manage the control repo with Terraform](/terragucci/guides/manage-the-control-repo-with-terraform/) |
| `modules.registry` serves module releases over the registry protocol from a bucket or Pages site | [Serve a module registry](/terragucci/guides/publish-modules/#serve-a-module-registry) |

## Estate and reports

| What | Where |
|---|---|
| `terragucci query` runs SQL over the reports bucket, in process | [Query the estate with SQL](/terragucci/guides/query-with-sql/) |
| An optional resource graph beside the estate page, with drift marked | [A resource graph beside the page](/terragucci/guides/see-every-project/#a-resource-graph-beside-the-page) |

## Moving to terragucci

| What | Where |
|---|---|
| `terragucci import hcp`, `import otf` and `import scalr` write `terragucci.yml` from a platform's workspaces over its API | [Import the workspaces](/terragucci/guides/coming-from-hcp-terraform-scalr-or-otf/#import-the-workspaces) |
| `terragucci import spacelift` and `import env0` write `terragucci.yml` from their config files and admin Terraform | [Coming from Spacelift or env zero](/terragucci/guides/coming-from-spacelift-or-env-zero/#import) |
| `terragucci import terragrunt-scale` keeps a Terragrunt Scale repo's plan and apply roles per environment | [Terragrunt Scale](/terragucci/guides/use-terragrunt/#terragrunt-scale) |
| Guides for HCP Terraform, Scalr and OTF, and for Spacelift and env zero | [Coming from HCP Terraform, Scalr or OTF](/terragucci/guides/coming-from-hcp-terraform-scalr-or-otf/), [Coming from Spacelift or env zero](/terragucci/guides/coming-from-spacelift-or-env-zero/) |
| A Standards section: the open standards terragucci uses, and its tacos.guru answers | [Standards](/terragucci/standards/) |

## Fixes

| What | Where |
|---|---|
| `unlock-state` on a choudoufu root under live markers says there is nothing to release | [Release a state lock](/terragucci/guides/release-a-state-lock/) |
| An Atmos pull request that changes a stack manifest locks the instances it reaches | [Pull requests](/terragucci/guides/use-atmos/#pull-requests) |
| A CDK Terrain pull request in a repo that synthesizes its stacks locks every stack | [Pull request locks](/terragucci/concepts/locking-and-staleness/#pull-request-locks) |
| On Forgejo, a pipeline with more than five levels of job dependencies plans | [Pipeline](/terragucci/reference/pipeline/) |
| A pull request whose format fix was pushed gets its lock answer | [Plan locks](/terragucci/reference/pipeline/#plan-locks) |
| A `live` block inside `terraform` makes a root | [Choose a binary](/terragucci/guides/use-a-binary/) |

---

# Standards

Source: https://intentius.io/terragucci/standards/

For a security review or a platform evaluation, each row below names a standard terragucci follows in its code today and links the page that shows it in use. Most of those pages name the smoke claims that prove it.

| Page | Answers |
|---|---|
| [tacos.guru](/terragucci/standards/tacos-guru/) | the 24 criteria and 5 gates of an independent Terraform platform evaluation, one by one |
| [Access and identity](/terragucci/standards/access-and-identity/) | SSO and RBAC: who decides each action, with no accounts of terragucci's own |

## Open standards

| Standard | terragucci uses it for | Shown in |
|---|---|---|
| OpenTofu and Terraform CLI | every plan and apply runs the binary you pin, against the state backend you already have; its plan JSON feeds policy and the report | [Choose your binary](/terragucci/guides/use-a-binary/) |
| Release checksums (`SHA256SUMS`) | a pinned binary the image lacks is installed in the job only when its checksum matches its release's | [Choose your binary](/terragucci/guides/use-a-binary/) |
| OpenID Connect federation | each job trades the forge's OIDC token for a short-lived role: AWS STS `AssumeRoleWithWebIdentity`, GCP workload identity federation, Azure federated credentials | [Credentials](/terragucci/reference/pipeline/#credentials) |
| OPA and Rego | policies over each plan with conftest or OPA, including HCP Terraform's policy-set input and `policies.hcl` | [Policy](/terragucci/reference/policy/) |
| OpenTelemetry (OTLP) | one trace per run and its metrics, sent as OTLP/JSON over HTTP to the endpoint in the standard `OTEL_EXPORTER_OTLP_*` variables | [Send traces and metrics](/terragucci/guides/send-traces-and-metrics/) |
| DORA metrics | deployment frequency, lead time, change failure rate and time to restore, computed from the audit trail | [Delivery metrics](/terragucci/reference/delivery-metrics/) |
| Model Context Protocol | `terragucci mcp`, a read-only MCP server on stdio over the estate, reports, state versions and audit trail | [Read the estate over MCP](/terragucci/guides/agent-read-over-mcp/) |
| SSH signatures | under `approval: sealed`, an approval is an `ssh-keygen -Y sign` signature checked against a file in ssh's `allowed_signers` format | [Set up the signers file](/terragucci/guides/approve-a-wave/#set-up-the-signers-file) |
| RFC 8785 (JSON Canonicalization Scheme) | a [plan digest](/terragucci/concepts/glossary/#plan-digest), `jcs1-sha256:`, is SHA-256 over the canonical JSON of the plan's change set, so key order never changes what an approval binds | [Approval binding](/terragucci/concepts/waves-and-approvals/#approval-binding) |
| Terraform module registry protocol | each module release is written as the protocol's static files to your bucket, so roots pin registry sources | [Serve a module registry](/terragucci/guides/publish-modules/#serve-a-module-registry) |
| OCI artifacts | modules publish as OCI packages that OpenTofu roots pin | [Publish your modules](/terragucci/guides/publish-modules/) |
| Conventional Commits and SemVer | commit types decide each module's next version | [Publish your modules](/terragucci/guides/publish-modules/) |
| SLSA provenance and in-toto | with `modules.attest`, each release carries SLSA v1 provenance in an in-toto statement, signed with cosign | [Attest each release](/terragucci/guides/publish-modules/#attest-each-release) |
| SPDX | each attested release carries an SPDX 2.3 SBOM of its providers and modules | [Attest each release](/terragucci/guides/publish-modules/#attest-each-release) |
| JSON Schema | the report, its indexes, the estate, the audit trail and DORA files ship schemas (draft 2020-12) a reader can validate against | [Report JSON schema](/terragucci/reference/report-schema/) |
| HMAC-SHA256 request signing | webhook events are signed over their body; the chat relay checks Slack's signing secret and the Teams outgoing webhook's HMAC | [Webhook event schema](/terragucci/reference/notify-event/#headers), [Approve from Slack and Teams](/terragucci/guides/approve-from-chat/) |
| Signed object URLs | reports open through S3 presigned links, GCS V4 signed URLs or Azure user delegation SAS, with no public bucket | [Keep reports in a bucket](/terragucci/guides/keep-reports-in-a-bucket/) |

## Next

- [Validation](/terragucci/reference/validation/): every smoke claim and its result.
- [Threat model](/terragucci/reference/threat-model/): what each job can reach.

---

# Access and identity

Source: https://intentius.io/terragucci/standards/access-and-identity/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/standards/access-and-identity/.
For this repo, list who can take each action in the page's table: read the forge's collaborators and their roles, the branch protection of the default branch and of the approvals branch, the `approval` key in terragucci.yml on the default branch, the principals in the signers file, and the trust policy of each role `oidc` names, through the forge's API or CLI and the cloud's CLI.
Report each action with the people or roles who can take it, and flag any action that the `approval` mode leaves unprovable.
Change nothing.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

Every terragucci stage is a job in your CI, so the controls you already run decide who can apply to production and show an auditor who did.

| Need | Comes from |
|---|---|
| SSO | the forge's sign-in: SAML or OIDC on GitHub, SAML on GitLab, LDAP or OAuth2 on Forgejo; Slack's or Teams' own sign-in for chat approvals |
| RBAC | forge permissions and branch protection for the code, the `approval` mode for gated waves, and cloud IAM for what each job's role reaches |
| Audit | the [audit trail](/terragucci/reference/audit-trail/): each approval with its approver, digest and time, and the apply that used it |

The signers file and `policy.override` are the only lists of people terragucci reads; both live in the repo. Offboarding someone takes them off the forge and chat workspace and out of both lists.

## Actions

| Action | Decided by |
|---|---|
| Open a pull request and get a plan | write access to the repo. The plan job's role is read-only and its trust names your repo; a fork's pull request gets no plan |
| Re-plan or apply from a comment | write access to the repo (on GitLab, Developer or above); anyone else gets no plan ([comment checks](/terragucci/reference/pipeline/#apply-from-a-comment)) |
| Merge | branch protection: required reviews and the required `terragucci/plan` status ([settings per forge](/terragucci/reference/threat-model/#branch-protection)) |
| Approve a waiting wave, `approval: ledger` | anyone who can push to [`chant/lifecycle`](/terragucci/concepts/glossary/#chantlifecycle), a forge branch rule |
| Approve a waiting wave, `approval: pr-review` | as under `ledger`, or a forge review of the pull request's head by a writer other than its author |
| Approve a waiting wave, `approval: sealed` | an ssh key in the [signers file](/terragucci/guides/approve-a-wave/#set-up-the-signers-file) on the default branch, which only a reviewed merge changes |
| Approve from Slack or Teams | the chat platform's sign-in, the user's line in the signers file, and a relay token that can only approve; under `sealed` the relay records nothing ([relay checks](/terragucci/reference/threat-model/#the-chat-relay)) |
| Override a policy denial | the people `policy.override` lists on the default branch ([overrides](/terragucci/reference/policy/#overriding-a-denial)) |
| Apply | the apply role, whose trust names the default branch alone; with `oidc.roles`, a role per environment ([scope state access](/terragucci/guides/scope-state-access/)) |
| Read or write a state | cloud IAM on each role's state keys; `config check` warns when one role reaches two environments |
| Export a state version | an approval by someone other than the requester, recorded in the audit trail ([export](/terragucci/guides/export-a-state-version/)) |
| Agents and MCP | write access to start an agent from a comment; no forge token and no cloud role in the agent's step, and its change comes back as a commit that plans like any other. `terragucci mcp` reads with its own environment's credentials and refuses approve ([agents](/terragucci/guides/agent-read-over-mcp/)) |

## Audit-grade approvals

:::caution
Under `approval: ledger`, the default, an approval line names whoever git says wrote it. Anyone who can push to `chant/lifecycle` can write a line in any name, so `ledger` does not prove who approved.
:::

Pick the mode that matches what you need to show:

| Mode | Proves |
|---|---|
| `ledger` | that the approved plan is the plan that applied |
| `pr-review` | as `ledger`, plus a forge review by someone other than the author, under their forge identity and so under your SSO |
| `sealed` | as `ledger`, plus an ssh signature by a key the signers file lists for that approver |

[Approve a waiting wave](/terragucci/guides/approve-a-wave/#approval-modes) sets each mode up, and the [approvals runbook](/terragucci/guides/approvals-runbook/) covers day-to-day use.

## Next

- [Threat model](/terragucci/reference/threat-model/): what each job can reach and what each mode stops.
- [tacos.guru](/terragucci/standards/tacos-guru/): where this answers the RBAC & SSO criterion.

---

# tacos.guru

Source: https://intentius.io/terragucci/standards/tacos-guru/

[tacos.guru](https://tacos.guru) holds Terraform automation platforms to one list of criteria. This page answers that list for terragucci, with each answer proven by a passing smoke claim on the [validation](/terragucci/reference/validation/) page.

tacos.guru has not scored terragucci, and this page claims no score from it.

Two blocks carry no claim. The dashed one, RBAC and SSO, stays with your forge, which already decides who signs in and who may approve a merge ([Access and identity](/terragucci/standards/access-and-identity/)). Pricing, outlined, has nothing to prove: terragucci is Apache-2.0 and runs in your CI. Hover or tap a block for its criterion.

## Evaluation

tacos.guru is an independent evaluator of TACOs (Terraform automation and collaboration software). It scores each platform from the vendor's public documentation. Its data, [`evaluation.json`](https://tacos.guru/evaluation.json), is the September 2026 dataset, and its page lets you change each weight and the pricing inputs and re-ranks the platforms as you do.

| Part | Meaning |
|---|---|
| Criteria | 24 features, each with a short description of what it asks |
| Category | Critical, High, Medium, Low or Nice-to-have; it sets the default weight from 5 down to 1 |
| Weight | the default from the category; you set each from 0 to 5 |
| Score | 0 None, 1 Limited, 2 Good, 3 Excellent, with a rationale per platform |
| Variants | chat is scored for Slack and Teams, version control for GitHub, GitLab, Bitbucket and Azure DevOps; you pick which counts |
| Pricing | a calculator of team size, resources, runs and states; a monthly cost up to $750 scores 3, up to $2,500 scores 2, up to $7,500 scores 1, quote-only 1, higher 0 |
| Gates | five pass or fail checks; a platform that fails one is marked disqualified and sorts below every platform that passes |

A platform's result is its weighted share of a perfect score:

```text
score = sum(score × weight) / sum(3 × weight) × 100%
```

## Criteria

A 3 below is what tacos.guru's description of the criterion asks for. The terragucci column links the page that shows it and names the claims that prove it on the [validation](/terragucci/reference/validation/) page.

| # | Criterion | Weight | A 3 | terragucci |
|---|---|---|---|---|
| 1 | CDK Terrain workflow | 5 | synth before plan; plan only the stacks a TypeScript change reaches | [`synth`](/terragucci/guides/plan-cdk-terrain-stacks/) runs before check and plan, and a pull request plans only the stacks it changes. `cdktn-synth`, `cdktn-affected` |
| 2 | OpenTofu support | 5 | OpenTofu first-class, its version pinned per stack | OpenTofu is the default binary. A root's `.opentofu-version`, `.terraform-version` or exact `required_version` picks its version, installed in the job and checked against the release's `SHA256SUMS` ([guide](/terragucci/guides/use-a-binary/)). `root-pins`, `pinned-install` |
| 3 | Self-hosted runners (no K8s required) | 5 | runners in your account; your own images | every stage is a job in your CI, on its runners, hosted or your own, picked by label per stage with [`runner`](/terragucci/guides/add-to-a-repo/#self-hosted-runners), in the published image or one you build on it ([architecture](/terragucci/concepts/how-it-works/), [`image`](/terragucci/guides/run-steps/)). `boot`, `image`, `runner-label` |
| 4 | RBAC & SSO | 5 | SAML or OIDC sign-in; roles by team and environment | no accounts and no login: sign-in is your forge's and roles are forge permissions plus cloud IAM. See [Access and identity](/terragucci/standards/access-and-identity/) |
| 5 | Linked-state orchestration | 5 | linked states deployed as one unit: a DAG, real unknowns across states, ordered applies, progress and gates | waves order the applies, each behind its gate; a root plans on its upstream's planned outputs, unknown where unknown, and plans again once the upstream applies; the [run view](/terragucci/concepts/waves-and-approvals/#the-run-view) shows each wave's state ([linked roots](/terragucci/concepts/waves-and-approvals/#linked-roots)). `linked-plan`, `linked-states`, `waves` |
| 6 | Drift detection | 4 | scheduled, per stack, with remediation | a scheduled run per root opens and closes the drift issue, and turns drift on a literal into a pull request ([guide](/terragucci/guides/turn-on-drift-checks/)). `drift`, `drift-close`, `respond-drift` |
| 7 | Cloud credentials (OIDC) | 4 | short-lived cloud credentials per stack, no static keys | each job trades the forge's OIDC token for a plan or apply role, per root glob with `oidc.roles`, on AWS, GCP and Azure ([credentials](/terragucci/reference/pipeline/#credentials)). `forgejo-oidc`, `report-oidc`, `oidc-clouds` |
| 8 | Pricing suitability | 4 | a low monthly cost at the calculator's inputs | Apache-2.0, with no license fee and nothing hosted; you pay for your CI minutes and your bucket |
| 9 | Repo scaffolding & codegen | 4 | backend, provider and workspace boilerplate from one declarative source | `terragucci generate` writes each root's backend, provider and version files from repo, glob and root settings, and `tf-check` refuses a hand edit ([guide](/terragucci/guides/generate-root-files/)). `generate` |
| 10 | State governance & RBAC | 4 | state access isolated per environment, fine-grained roles, export, cross-state tracking | a role per environment scoped to its state keys ([guide](/terragucci/guides/scope-state-access/)), an approved and audited [export](/terragucci/guides/export-a-state-version/), [cross-state edges](/terragucci/guides/track-cross-state-edges/), [state versions](/terragucci/guides/find-a-state-version/) and [migrations](/terragucci/guides/move-resources-between-roots/). `state-roles`, `state-export`, `state-edges`, `state-versions`, `migrate-split` |
| 11 | Migration from Atlantis | 3 | a documented path, `atlantis.yaml` import or comment compatibility | `terragucci import atlantis` and `import digger` write `terragucci.yml`, and `atlantis plan` and `atlantis apply` comments work behind a setting ([guide](/terragucci/guides/coming-from-atlantis-or-opentaco/)). Teams on a hosted platform have guides too: [HCP Terraform, Scalr or OTF](/terragucci/guides/coming-from-hcp-terraform-scalr-or-otf/), [Spacelift or env zero](/terragucci/guides/coming-from-spacelift-or-env-zero/). `import-atlantis`, `comment-atlantis` |
| 12 | Custom workflows, hooks & gates | 3 | any step before or after each stage, custom images, blocking gates | [`steps`](/terragucci/guides/run-steps/) run before and after init, plan, apply and drift; a failing step stops the wave or holds it at the gate; `image` runs a root's jobs in your own image. `steps-before-plan`, `steps-stop`, `steps-gate`, `image` |
| 13 | Private module registry | 3 | a monorepo-friendly Terraform and OpenTofu registry | each release is written as the module registry protocol to your bucket, with namespaces by tag prefix and `tofu test` before release ([guide](/terragucci/guides/publish-modules/#serve-a-module-registry)). `module-registry`, `publish` |
| 14 | Cost estimation | 3 | cost estimates on each pull request | Infracost figures in the plan note, in the policy input, and as a threshold that holds a wave at its gate ([guide](/terragucci/guides/estimate-cost/)). `cost-estimate`, `cost-gate`, `cost-policy` |
| 15 | Policy as code | 3 | portable OPA and Rego on plans | conftest or OPA over each plan, HCP Terraform policy sets and `policies.hcl`, from the repo or a shared source at a pinned ref ([reference](/terragucci/reference/policy/)). `policy-opa`, `policy-hcl`, `policy-source` |
| 16 | AI: trusted PR review | 3 | a model reviews a change's intent against its plan, from default-branch instructions, on your own model | `review.agent` runs your model on the description, diff and plan with instructions from the default branch and no forge token; the note approves nothing ([guide](/terragucci/guides/agent-review-a-pull-request/)). `review-agent`, `review-policy` |
| 17 | Collaboration integration | 4 | interactive approvals in Slack and Teams | `terragucci relay`, in your cloud, records a Slack click or a Teams reply as the approver's own approval; drift notices carry a re-plan button ([guide](/terragucci/guides/approve-from-chat/)). `chat-approve`, `chat-approve-teams`, `chat-replan` |
| 18 | VCS integration | 3 | plan comments and checks, merge gating, operations from comments | a plan note and status on each pull request, comment commands for plan and apply, on GitHub, GitLab and Forgejo ([guide](/terragucci/guides/re-plan-from-a-comment/)). Bitbucket and Azure DevOps get no pipeline. `comment-plan`, `comment-apply`, `fork-no-plan` |
| 19 | Observability | 3 | run events, metrics and audit to Datadog, OTel or webhooks | OpenTelemetry traces and metrics to any OTLP endpoint ([guide](/terragucci/guides/send-traces-and-metrics/)), signed webhooks ([event](/terragucci/reference/notify-event/)) and an [audit trail](/terragucci/reference/audit-trail/). `traces`, `metrics`, `notify-webhook`, `audit` |
| 20 | Visualizations / graphs | 2 | resource and dependency graphs, deployment views | the estate page draws roots by wave with cross-project edges; the run view shows blast radius and a timeline ([guide](/terragucci/guides/see-every-project/)). `estate-graph` |
| 21 | AI: agentic ops & MCP | 2 | an MCP server, state context, agents that act on drift | [`terragucci mcp`](/terragucci/guides/agent-read-over-mcp/) serves the estate read-only, and the [drift agent](/terragucci/guides/agent-fix-drift/) opens a pull request that plans like any other. `mcp-last-apply`, `drift-agent` |
| 22 | Ephemeral environments | 1 | short-lived environments with a TTL | a copy of the named roots per pull request, destroyed through a planned destroy on close or when its TTL passes ([guide](/terragucci/guides/ephemeral-environments/)). `ephemeral-pr`, `ephemeral-ttl` |
| 23 | Terraform provider | 1 | manage the platform through Terraform | the terragucci provider owns a [control repo](/terragucci/concepts/control-repo/)'s projects and defaults, and plans show each change ([guide](/terragucci/guides/manage-the-control-repo-with-terraform/)). You build it from the repository; its publication to the OpenTofu and Terraform registries is pending ([#659](https://github.com/INTENTIUS/terragucci/issues/659)). `provider-project` |
| 24 | Multi-cloud support | 1 | clouds beyond AWS | OIDC to AWS, GCP and Azure, and reports in S3, GCS or Azure Blob Storage ([guide](/terragucci/guides/keep-reports-in-a-bucket/)). `oidc-clouds`, `blob-gcs`, `blob-azure` |

## Gates

| Gate | Checks | terragucci |
|---|---|---|
| G1 | no Kubernetes required | jobs in your CI; nothing to install in a cluster |
| G2 | self-hosted runners in your cloud account | your CI's runners, wherever you run them |
| G3 | a CDK Terrain synth step before plan | the `synth` key ([guide](/terragucci/guides/plan-cdk-terrain-stacks/)). `cdktn-synth` |
| G4 | actively maintained: recent releases, at least three active committers, the core team still on it | a judgement of the maintainers, not a feature, so this page makes no claim for it. The [releases](https://github.com/INTENTIUS/terragucci/releases) and [commits](https://github.com/INTENTIUS/terragucci/commits/main) are public |
| G5 | OpenTofu support (advisory) | the default binary. `root-pins` |

## Next

- [Access and identity](/terragucci/standards/access-and-identity/): the forge and cloud permissions that stand in for accounts and roles.
- [Standards](/terragucci/standards/): the open standards terragucci reads and writes.
- [Validation](/terragucci/reference/validation/): every claim named here, with its result.

---

# A wave that changed

Source: https://intentius.io/terragucci/tutorial/changed-wave/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/tutorial/changed-wave/.
In the terragucci clone with the example booted, run `just example change destroy` and `just example change module-bump` and summarize both plan notes. Then stop and print the page's merge and approve commands for me. Do not run them.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

:::note[Where the example stands]
Booted with `just example up`. `just example reset` gets you back to that from any step.
:::

An approval covers the plans you read and no others.

1. Open the destroy change and merge it, so wave 4 waits:

   ```bash
   just example change destroy
   just example merge destroy
   ```

2. Approve wave 4, as on the previous page:

   ```bash
   just example approve
   ```

3. Before you run the wave's job again, change the shared module, so every root in wave 4 plans again:

   ```bash
   just example change module-bump
   just example merge module-bump
   ```

The wave's plans now differ from the approved ones, so it applies nothing:

| You see | Where |
|---|---|
| the job fails with exit code 4 | the wave's job |
| the approved digest beside the new one, and each root whose plan moved | the job's log |

`npx terragucci respond wave-refused --approved <approved report> --current <current report> --wave 4` prints what changed; [Fix a refused wave](/terragucci/guides/fix-a-refused-wave/) describes the reports.

| If the new plan is | Do |
|---|---|
| what you meant | approve the new digest and run the job again |
| not what you meant | revert the change |

Had the job run between steps 2 and 3, wave 4 would have applied the destroy under your approval. The module bump's wave 4 would then wait for its own approval instead of refusing.

---

# Drift

Source: https://intentius.io/terragucci/tutorial/drift/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/tutorial/drift/.
In the terragucci clone with the example booted, run the `just example` commands on the page. Summarize what the drift issue names, and where it differs from the page.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

:::note[Where the example stands]
Booted with `just example up`. `just example reset` gets you back to that from any step.
:::

Someone deletes a queue in the console.

1. The scenario deletes it through the API.

2. Run the `drift` job by hand from the Actions tab, or wait for six in the morning. Its `-refresh-only` plan of every root compares state with what exists in [floci](/terragucci/concepts/glossary/#floci) and never reads the code, so a change waiting on main is not drift. The report lists the deleted queue under deletes, in `envs/staging/orders` as `module.service.aws_sqs_queue.jobs`.

   :::note
   floci does not keep tags, so unlike AWS it shows tags as drifted on every root. Look for the entry marked deleted outside Terraform.
   :::

3. Open the issue the job opened, `terragucci: drift found`. It names `envs/staging/orders` and the queue `shop-staging-orders-jobs`. A second run updates it.

Applying the code recreates the queue, which `just example reset` does. The next drift run then closes the issue on AWS; on floci the tag entries keep it open.

---

# Your first pull request

Source: https://intentius.io/terragucci/tutorial/first-pull-request/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/tutorial/first-pull-request/.
In the terragucci clone with the example booted, run the `just example` commands on the page. Summarize what the plan note and the failed check say, and where they differ from the page.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

:::note[Where the example stands]
Booted with `just example up`, nothing changed yet. `just example reset` gets you back here from any later step.
:::

## Change one root

Orders in dev should keep unpicked jobs for seven days instead of four: one line in `envs/dev/orders/main.tf`.

1. One command makes the branch and opens the pull request. The push and the pull request each start a run: the pull request's run posts the plan note, the push's run is the check. The output prints both run numbers.

2. Open the pull request link in Forgejo:

3. Look at the push's run, the second link printed. `tf-check` runs on the branch push, and on a pull request only from a fork: a format check, then `validate` for every root. Both steps pass. The plan note is a comment in the conversation:

## Break the formatting

1. Add a badly formatted file:

   ```hcl
   locals {
       team   = "orders"
     owner = "shop"
   }
   ```

2. The scenario opens it as a second pull request. The check fails, and `just example logs` prints the file and the change `tofu fmt` would make.

3. In Forgejo the failed step is "Format check and validate, every root":

4. Run `tofu fmt -recursive` in your own repo and the check goes green again.

## Recap

Every push runs the check stage on every root. It needs no cloud credentials, because it never plans.

---

# Publishing and pinning modules

Source: https://intentius.io/terragucci/tutorial/modules/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/tutorial/modules/.
In the terragucci clone with the example booted, run `just example change pin` and summarize the rollout pull request it opens: the roots it covers and the `ref` each moves.
`just example change pin` runs the rollout against the local Forgejo, which opens that pull request; that is the one exception to the line below.
Then stop and print the page's merge and `just example rollout` commands for me. Never merge the rollout pull request.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

:::note[Where the example stands]
Booted with `just example up`. `just example reset` gets you back to that from any step, and removes the release tags this page makes.
:::

When roots pin a published version, a module change reaches no root until a pin moves. `tf-publish` publishes a module version, and `tf-rollout` moves the pins with one pull request per wave.

1. Run the scenario:

   ```bash
   just example change pin
   ```

   It tags `modules/service` at `1.0.0` with `tf-publish` and pins the twelve service roots to that tag on main. The changed module then goes out as `1.1.0`, and `terragucci rollout modules/service --mode apply` runs. Here `apply` means opening the pull request; no `terraform apply` runs until it merges.

2. Read the canary wave's pull request, for the four dev services. The rollout took the newest version and moved each of their pins:

   | Version | Git tag, the roots' `ref` | Roots pinned to it |
   |---|---|---|
   | `1.0.0` | `modules/service/v1.0.0` | every service root whose wave has not merged |
   | `1.1.0` | `modules/service/v1.1.0` | the dev services, once this pull request merges |

3. Merge it, and let the apply on the merge commit finish.

4. Open the next wave:

   ```bash
   just example rollout
   ```

   It runs the same `terragucci rollout` command. Each run takes at most one step, so the next wave opens only once the last has applied.

[Publish your modules](/terragucci/guides/publish-modules/) adds the publish job, and [Roll out a new module version](/terragucci/guides/roll-out-a-module-version/) has every step.

---

# One note for fifteen plans

Source: https://intentius.io/terragucci/tutorial/one-note/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/tutorial/one-note/.
In the terragucci clone with the example booted, run the `just example` commands on the page. Summarize what the plan note says about the twelve roots, the outlier and any destroy.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

:::note[Where the example stands]
Booted with `just example up`. `just example reset` gets you back to that from any step.
:::

Every queue in every service should wait 60 seconds before retrying a job. That is one line in `modules/service`, and twelve roots call the module.

Open the pull request link it printed, on Forgejo at `localhost:3300`; the plan note is the comment in the conversation.

terragucci plans only the twelve service roots the change reaches and posts one note. Eleven roots take the identical change and appear as one group. Prod payments sits apart, because its dead-letter queue changes too.

GitHub and GitLab get the same single comment, here for a change to one root:

**GitHub**

**GitLab**

The note links to the full report. Its links start with `http://forgejo:3000`, which your browser cannot reach; open them at `http://localhost:3300` instead. The report opens on what differs and folds the eleven identical plans into one.

Next, try `just example change replace` and `just example change destroy`. Each is named on its own, never folded into a group.

---

# See your runs

Source: https://intentius.io/terragucci/tutorial/see-your-runs/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/tutorial/see-your-runs/.
In the terragucci clone with the example booted, run `just see-runs` and tell me what the Pipeline health, Rollouts and waves, Drift and Runs dashboards in Grafana at http://localhost:3310 show, and where they differ from the page.
`just see-runs` runs the waves of a scratch copy of the example against floci only; that is the one exception to the line below.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

:::note[Where the example stands]
Booted with `just example up`. `just example reset` gets you back to that from any step.
:::

Every stage can send traces and metrics to an OpenTelemetry collector. `dashboards: true` makes `init` write the Grafana dashboards and alert rules too. Send three runs of the example to Grafana:

```bash
just see-runs
```

It runs three stages on a copy of the example, with `OTEL_EXPORTER_OTLP_ENDPOINT` set:

| Stage | Run | Result |
|---|---|---|
| `tf-plan` | the module-bump change | success |
| `tf-drift` | after deleting staging orders' jobs queue from [floci](/terragucci/concepts/glossary/#floci), as on the [Drift](/terragucci/tutorial/drift/) page | success |
| `tf-apply` | the waves, with the gate set to `always` | wave 1 has nothing to change and passes; wave 2 waits for an approval |

The ledger goes to a scratch repo, so the Forgejo example stays as it was.

The dashboards are in the `terragucci` folder of Grafana at [localhost:3310](http://localhost:3310). The picture below shows the minutes the runs took.

## Pipeline health

Each stage run is one span counted by stage and outcome. The plan and drift runs count as successes and the waves as `nothing` and `waiting`, which are not errors.

## Rollouts and waves

No wave was refused or failed. Past `wave_wait` (four hours by default), a waiting wave fires `TerragucciWaveWaiting`.

## Drift

The `tf-drift` run finds the deleted queue in staging orders, and floci's missing tags on every root. `TerragucciDriftOld` fires once the drift is older than `drift_age` (a day).

## Runs

The table at the bottom lists each run's trace; opening one shows OpenTofu's spans inside each root.

[Traces and metrics](/terragucci/reference/observability/#dashboards-and-alerts) lists every dashboard, the alert rules and the collector settings.

## In your own repo

Add the key and run `init`:

```yaml
dashboards: true
env:
  OTEL_EXPORTER_OTLP_ENDPOINT: https://otel-collector.example.com:4318
```

`init` writes the dashboards under `observability/terragucci/`. Point Grafana and Prometheus at that directory, and give your collector the `spanmetrics` connector.

---

# The same shop on Terragrunt

Source: https://intentius.io/terragucci/tutorial/terragrunt/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/tutorial/terragrunt/.
In the terragucci clone, run `just example-terragrunt up`, then `just example-terragrunt change module-bump` and `just example-terragrunt change new-service`. Summarize which units each plan note covers and why, and where it differs from the page.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

:::note[Where the example stands]
This path uses `example-terragrunt/`, beside the plain example. Boot it with `just example-terragrunt up`; `just example-terragrunt reset` gets you back to it from any step.
:::

## The layout

Each environment is a directory of units:

```
root.hcl                 state in the shop's bucket, and the AWS provider every unit gets
live/common.hcl          settings every unit reads with read_terragrunt_config
live/dev/platform        the environment's logs bucket
live/dev/orders          a service; its dependency block reads platform's outputs
modules/service          the module every service uses; it reads policy.json with file()
```

There is no `roots:` setting. On finding `root.hcl` `init` asks Terragrunt for the units and writes the pipeline, which the example already has. In your own repo run `npx terragucci init` at the root, and it prints:

```
found Terragrunt (root.hcl): 15 units in 5 waves from terragrunt find, terragrunt 1.1.6 (the image) calling tofu 1.13.1 (terragucci.yml), parallelism 16 (the s3 backend), forge forgejo (.forgejo/workflows)
```

Each wave is one dependency layer, the dev canary's first. Its job plans with one `terragrunt run --all`, and a second `run --all` applies the saved plans once the gate lets it.

| Wave | Units | Job |
|---|---|---|
| 1 | dev platform | `apply-wave-1` |
| 2 | the four dev services, which read it | `apply-wave-2` |
| 3 | staging and prod platform | `apply-wave-3` |
| 4 | the staging and prod services, except prod search | `apply-wave-4` |
| 5 | prod search, which goes out after prod orders | `apply-wave-5` |

Under the default `on-destructive` gate a wave that destroys or replaces something waits for an approval of its set digest. The example's [`chant.workspace.json`](/terragucci/concepts/glossary/#chantworkspacejson) lists the five gates, so it runs `approval: sealed` and each approval must be sealed.

A service plans only after its platform applied, so it reads the platform's real outputs.

## The check stage

The check job runs, in order:

1. `tofu fmt -check -recursive -diff .`, for the modules the units call
2. `terragrunt hcl fmt --check`
3. `terragrunt hcl validate --inputs`
4. `terragucci check-pins`, which checks each unit's `terraform { source }` when [`modules.require: attested`](/terragucci/guides/publish-modules/#require-attested-releases) is set
5. `terragucci check-policy`, which runs the policy's tests when `policy` is set

An unformatted `.hcl` file fails the job by name:

```bash
just example-terragrunt change unformatted
```

## A file Terragrunt does not see

`modules/service` reads `policy.json` with `file()`, which Terragrunt's change detection does not follow. terragucci adds the units it reaches, and says why:

```bash
just example-terragrunt change module-bump
```

The plan covers the 12 service units and none of the platforms. Each unit in the report names `modules/service/policy.json` as its reason.

## A new unit and its upstream, in one change

The `new-service` scenario adds `ledger`, which makes a bucket, and `billing`, which reads the bucket's name from it. Ledger has no outputs yet, so Terragrunt on its own would hand billing its `mock_outputs`.

```bash
just example-terragrunt change new-service
```

The plan job plans ledger, then plans billing on the bucket name from ledger's plan, `shop-tg-dev-ledger`; the note lists billing as planned on ledger's planned outputs. After the merge ledger applies in wave 1 and billing plans again in wave 2 on its real outputs.

Billing's dependency block has no allow-list, so its mocks could stand in for `apply`. The report's tips name it `TF041`, as for `live/prod/email`.

## Explicit stacks

The example's units are each in their own directory. A repo whose units come from a `terragrunt.stack.hcl` gets the same pipeline: every job runs `terragrunt stack generate` first, and the generated units take their waves from their `dependency` blocks. [Explicit stacks](/terragucci/guides/use-terragrunt/#explicit-stacks) lists what each stage does with them.

## Credentials

Map a plan role and an apply role by path; a unit that sets its own `iam_role` keeps it:

```yaml
terragrunt:
  credentials:
    "live/prod/**": { plan: arn:aws:iam::111122223333:role/prod-plan, apply: arn:aws:iam::111122223333:role/prod-apply }
```

[The generated pipeline](/terragucci/reference/pipeline/#terragrunt) has the details.

---

# Tips

Source: https://intentius.io/terragucci/tutorial/tips/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/tutorial/tips/.
In the terragucci clone with the example booted, run `just example change float` and summarize the tip the plan note and report give, and where it differs from the page.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

:::note[Where the example stands]
Booted with `just example up`. `just example reset` gets you back to that from any step.
:::

```bash
just example change float
```

Dev search now lets the AWS provider float to any 6.x release (`~> 6.0`).

| What | Where |
|---|---|
| tip | `terragucci-floating-range`, naming the root and how to pin the version |
| plan note | a line counting the tips |
| report | a Tips section |

Tips never fail a run or change a plan or its digest; `tips: false` removes them. [Tips](/terragucci/reference/tips/) lists the rules.

---

# Waves and approvals

Source: https://intentius.io/terragucci/tutorial/waves/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/tutorial/waves/.
In the terragucci clone with the example booted, run `just example change destroy` and read the plan note. Then stop and print the `just example merge destroy` and `just example approve` commands for me. Do not run either of them.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

:::note[Where the example stands]
Booted with `just example up`. `just example reset` gets you back to that from any step.
:::

The apply is one job per wave, canary first.

| Wave | Roots |
|---|---|
| 1 | the dev platform root |
| 2 | the four dev services |
| 3 | the staging and prod platform roots |
| 4 | their eight services |

With the default gate `on-destructive` a wave waits only when its plans destroy or replace something. This scenario makes one destroy.

That pull request drops the records table of staging email. Its note names the destroy at the top:

The example runs `approval: sealed`, so its approvals need a key. Your own repo defaults to `ledger`, with no key:

| `approval` | Where | An approval counts when |
|---|---|---|
| `sealed` | the example, whose [`chant.workspace.json`](/terragucci/concepts/glossary/#chantworkspacejson) lists its wave gates | it is sealed by a key listed in `.chant/allowed_signers` on the default branch as it was before the merge being applied |
| `ledger` | your own repo, by default | it approves the wave's digest; no key needed |

[Approve a waiting wave](/terragucci/guides/approve-a-wave/) shows both, and `pr-review`.

1. Merge it with `just example merge destroy`, or in Forgejo signed in with the account `just example up` printed. That command's first run also generates a key for the example's sealed mode and commits it to `.chant/allowed_signers` on main; that file lists who may approve.

2. Wave 4 plans the destroy and stops. Its job exits with code 3 and prints the approve command:

3. Read the wave's plans in the report. The [`terragucci approve`](/terragucci/reference/cli/#approve) command carries the digest the wave planned, so the approval covers those plans and no others.

4. Approve with the example's generated key:

   ```bash
   just example approve
   ```

   It runs `terragucci approve wave-4` with that key.

5. Run the wave's job again, and wave 4 applies. A plan that changes afterwards is not covered, as the next page shows.

To make every wave wait, set `gate: always` in `terragucci.yml`.

---

# Clean up, then your own repo

Source: https://intentius.io/terragucci/tutorial/your-repo/

## Optional: hand this page to your coding agent

```text
Read https://intentius.io/terragucci/tutorial/your-repo/.
In the terragucci clone, run `just example down` and confirm the local stack is gone.
Then, in my own repository, run `npx terragucci init --dry-run --json` and show me the findings, run `npx terragucci init`, and open a pull request with the files it wrote. Do not create secrets.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.
```

:::note[Where the example stands]
Booted with `just example up`. `just example reset` gets you back to that from any step.
:::

```bash
just example down
```

That removes the whole local stack, Terragrunt shop included.

In your own repository `terragucci init` finds the roots and the binary and the forge itself. Most repos need no config.

[Get your first plan note](/terragucci/getting-started/) takes you from `npm i -D @intentius/terragucci` to a plan note on a pull request. A person approves the waves that wait with [`terragucci approve`](/terragucci/reference/cli/#approve); under `approval: sealed`, [set up the signers file](/terragucci/guides/approve-a-wave/#set-up-the-signers-file) before the first merge.

[terragucci.yml keys](/terragucci/reference/config/) covers the config, and [Set up with a coding agent](/terragucci/getting-started/agents/) has a prompt for an agent to do it.