The plan report
Optional: hand this page to your coding agentThe steps work by hand too.Show the whole prompt
Read https://intentius.io/terragucci/reference/report/.
For this branch, list the roots terragucci will plan and why, from the section Roots a change plans.
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
Section titled “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.
Kept as the terragucci-report artifact, and the note names the run.
The job’s artifacts hold the HTML report, and the note links it. The merge-request widget reads gitlab-terraform.json.
The same as GitHub.
With a served bucket the copy there is linked instead.
Run it locally from the repo:
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 |
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) |
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 lists the flags.
Roots a change plans
Section titled “Roots a change plans”A pull request plans only the roots its change reaches, found from the code itself: the files in each root, the local modules it calls, the var files it reads and the state reads between roots. There are no include or exclude patterns to write and keep in step with the code. /terragucci plan and a workflow_dispatch re-plan plan the same selection again on the pull request’s head, and a re-plan that names a root the change does not reach plans nothing and says so. The job log names each root and why it planned.
| The change | Plans |
|---|---|
| any file in a root’s directory, a README included | that root |
a file in a local module (source = "./..." or "../..."), followed through modules that call modules |
every root that calls it |
a root whose state another root reads through terraform_remote_state, or a root waves.after puts another after |
that root, then each reader or later root, followed through |
a var file, a symlink’s target, or a setting in terragucci.yml |
below |
| any other file outside every root, such as a top-level README | nothing, and the note says so |
A registry or git module is not followed: a new version reaches a root when its pin moves (rollouts). A file a root reads with file() counts when it sits in the root’s directory or a local module’s.
| The change | Plans |
|---|---|
a unit’s files, the files it includes, or a file its local module reads that Terragrunt does not report, such as a file() read |
that unit |
a value in a terragrunt.stack.hcl |
the unit that value feeds |
| a unit removed | its destroy, planned from the base |
a unit others name in a dependency or dependencies block |
that unit; its dependents are previewed outside every digest under terragrunt.dependents: plan, the default |
terragrunt.exclude leaves a unit out of every plan. Use Terragrunt has the rest.
| The change | Plans |
|---|---|
| a component, a stack manifest or an import | each instance whose written component, var file or backend differs from the base’s |
an instance others depend on through dependencies.components, settings.depends_on or !terraform.state |
that instance and its dependents |
Use Atmos has the rest.
| The change | Plans |
|---|---|
| a stack’s files, its generated code included | that stack |
a stack others are ordered after by after, before, nesting or an input |
that stack and the stacks after it |
A change to globals reaches a stack through the code terramate generate writes into it. Use Terramate has the rest.
| The change | Plans |
|---|---|
any file the synth command reads |
the stacks whose synthesized files or local modules differ from the base’s, new and removed stacks, and the stacks that read their state; the note counts the unchanged ones |
the synth command in terragucci.yml |
every stack |
Plan CDK Terrain stacks has the rest.
A root the pipeline does not list yet, such as one a pull request adds, plans once terragucci init runs again and lists it.
Changes outside every root
Section titled “Changes outside every root”A pull request also plans the roots a change outside their directories reaches. The job log names each one and why, such as affected: envs/prod/app reads envs/prod/shared.tfvars, which changed.
| The change | Plans |
|---|---|
a var file a -var-file in TF_CLI_ARGS or TF_CLI_ARGS_plan names, set in env or the job’s environment; the path is relative to each root |
the roots that read it |
a file or directory a symlink under a root points at, such as a shared .terraform.lock.hcl, provider file or .auto.tfvars |
the roots that link it |
version, generate, pass, env, oidc or secrets in terragucci.yml, resolved per root, its globs included |
the roots whose settings differ from the base’s |
synth in terragucci.yml |
every synthesized root, and the note says the command changed |
a file the synth command reads |
the roots whose synthesized files differ from the base’s |
policy or approval in terragucci.yml, ci.hooks in chant.workspace.json, or the policy directory |
no root: the run reads these from the base, so the change takes effect once it merges |
Reviewer view
Section titled “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
Section titled “The plan note”The note comments the plan back to the pull request, grouped. A group of two roots shows one 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 |
|---|---|
| Total line | the run’s changes over every root whose plan changes something, counted as the binary’s Plan: line counts them (a replacement adds one and destroys one): 3 to add, 2 to change, 0 to destroy across 3 roots, with to forget when a plan forgets; on a tf-apply wave’s note, the wave’s total. It comes from totals and totals_roots in report.json, and is left out when no plan changes anything |
| 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 |
| Changes on every run | with reports set, a folded table after the groups: each planned update or replacement that the root’s last 3 applied waves in a row also made, to the same address with the same action and attributes, read from the project’s changes.json in the bucket. Each row names the root, the address, the attributes and how many applied waves in a row made it, with the usual fixes under the table: build the artifact reproducibly, lifecycle { ignore_changes }, or pin the provider version that normalises the value. A group whose every change is in it shows its attribute names without the diff. The change stays in the plan, its digest and the gate: such a replacement is still named first and still holds a wave under on-destructive. Without reports, nothing is marked and the plan job’s log says why |
| 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 |
| Composed run | with waves.compose: one block naming the roots that plan and apply as one run and the wave that runs them, a table of each root’s module and changes, and the values read before they were known; the wave’s row says composed. On a tf-apply wave, once the run ends, what came of each root and its state. When the change applies in waves, one line that says why |
| Cone plans | with binary: choudoufu (choudoufu), each root planned with -cone=<base>: the cone’s blocks and the estate’s, or, when choudoufu planned the whole estate, its reason and the guard that tripped (Cone plans) |
A Terragrunt unit’s plan is kept as JSON only, so its group shows the attribute names.
Comment limits
Section titled “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
Section titled “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
Section titled “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
Section titled “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. The HTML report is one file that makes no network calls.
Script access
Section titled “Script access”report.json sits beside every report.html, which also carries it inline:
sed -n '/id="terragucci-report"/,/<\/script>/p' report.html | sed '1d;$d' | jq '.named[] | select(.action == "delete") | .address'Report JSON schema lists every field.
Approvals stay on your repo’s chant/lifecycle branch. The report links to each record and never copies it. The audit trail reads the two together.
Sensitive values
Section titled “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 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
Section titled “Report storage”By default a report is a CI artifact of the plan’s run, kept as long as your forge keeps artifacts. On GitHub and Forgejo the plan-note job keeps it: the plan job hands its report on as job outputs, up to about 330 KB gzipped on GitHub and 3 MB on Forgejo. A larger report is cut to the note, the status, report.json and drift-schedule.json, and the plan log says so; a bucket keeps the whole report. To keep reports 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 says why reports get their own identity.
reports:
bucket: s3://acme-terragucci
prefix: reports
url: https://reports.acme.example
role: arn:aws:iam::123456789012:role/terragucci-reportsurl 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.
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.jsonWith 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.
The report index
Section titled “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, one page for every project, and terragucci audit, which reads each tf-apply row’s report |
| Retention | your bucket’s lifecycle rule |
terragucciHelp setting it up: Intentius
These docs count page views and clicks with PostHog. They set no cookies, store nothing in your browser, and send nothing when your browser asks not to be tracked.