Architecture

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 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 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, a writer’s /terragucci apply comment applies the open head instead (on GitLab, with the comments schedule). The guide lists what it refuses.

4. The waves: tf-apply runs one job per wave, waves.canary roots first, then dependency order. With waves.jobs, 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. A person runs terragucci approve to record an approval on chant/lifecycle, 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 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 and the signers file
your cloud	your state (with 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)

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 sets it up on a repository.
• The tutorial runs each step on a 15-root example on your laptop.
• Waves and approvals explains the waves and the gate.
• The approvals runbook has the commands for signers, pending waves and refusals.
• The glossary defines terragucci’s words and lists the ones that mean something else in Terraform.