Skip to content
terragucciDocs

CDK Terrain

llms.txtlists every page for an agent

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, choudoufu, GitLab

On Terraform

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

On choudoufu

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

On GitLab

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

First step

Plan CDK Terrain stacks

Proof

CDK Terrain, on Forgejo

  • Plan and reviewPlan and review, CDK Terrain4 checks, all proven.
    • with synth set to npx cdktn synth the pipeline synthesizes the CDK Terrain stacks before check, apply and tf-plan, and tf-plan plans the stack the change reaches
    • with synth set a pull request that changes one CDK Terrain stack plans that stack alone, and the plan note says how many stacks were unchanged
    • with synth set the tips job synthesizes the CDK Terrain stacks and opens the canary tip, and says the pin and lock file tips are left out
    1 more on the validation page.
  • Approve and applyApprove and apply, CDK Terrain1 check, proven.
    • with synth set each apply wave synthesizes the CDK Terrain stacks and applies its stack behind the gate: dev once wave 1 is approved, prod once wave 2 is
  • Locks and safetyLocks and safety, CDK Terrain1 check, proven.
    • with synth and apply.when: pull-request, a pull request applied on a comment locks every CDK Terrain stack, since its change to the app can reach any, and a second pull request that changes a stack is refused with the stack and the holder named, its state left as the first applied it
  • PolicyPolicy, CDK TerrainNo check recorded.
  • DriftDrift, CDK TerrainNo check recorded.The drift pull request is refused: a live value belongs in the app that writes the stacks.
  • Chat and notifyChat and notify, CDK TerrainNo check recorded.
  • Reports and visibilityReports and visibility, CDK TerrainNo check recorded.
  • ModulesModules, CDK TerrainNo check recorded.Rollouts are refused: the pin is in the app that writes the stacks.
  • State and migrationState and migration, CDK Terrain1 check, proven.
    • a migration moves a resource between two CDK Terrain stacks, whose roots are cdk.tf.json: tf-plan proves it with no change, wave 1 waits for its digest, and once approved writes both states under their lock files
  • Agents and pull request environmentsAgents and pull request environments, CDK Terrain1 check, proven.
    • with synth set, opening a pull request runs the synth command in its checkout and applies its own copy of a CDK Terrain stack at the key suffixed -pr-<n>, beside the state of the stack itself, and closing it destroys the copy on the record
  • Setup and runtimeSetup and runtime, CDK Terrain2 checks, all proven.
    • with synth set init refuses the drift pull request and rollouts as config errors saying why, and with respond.drift: attribute the drift job runs no pull request
    • with synth set init and terragucci generate refuse a generate key as a config error that names the CDK Terrain constructs that set a backend
    A CDK Terrain app cannot run in a Terragrunt repo, which takes no synth.
  • proven passes, and fails with the feature cut out
  • not supported not supported by design; a corner mark means part of the area
  • none no check recorded

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

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

You can count on

Then read

Tasks
Plan CDK Terrain stacks
Background
Waves and approvals
Details
terragucci.yml keys

terragucci

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.