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

On Terraform

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

On choudoufu

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

On GitLab

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

First step

Use Atmos

Proof

Atmos, on Forgejo

• Plan and review2provenPlan and review, Atmos2 checks, all proven.
  • a pull request that changes one Atmos instance plans that instance and the instances whose dependencies.components name it, and no other
  • the check job of an Atmos repo runs atmos validate stacks before it writes the instances, and fails on a manifest Atmos refuses, with the error Atmos gives
• Approve and apply3provenApprove and apply, Atmos3 checks, all proven.
  • init names one root per Atmos instance, <stack>/<component>, from atmos describe stacks, and cuts a wave per layer of dependencies.components: each dependent instance applies in the wave after its dependency, behind its own gate
  • an Atmos wave whose plans changed after approval applies nothing and names the instance that moved; once its new plans are approved it applies the plans whose digest was approved
  • an Atmos instance whose stack reads an unapplied instance with !terraform.state is held back, never planned on a stand-in, and applies on the output of the upstream once it has applied
• Locks and safety1provenLocks and safety, Atmos1 check, proven.
  • with apply.when: pull-request in an Atmos repo, a pull request applied on a comment locks the Atmos instances it reaches (every instance, for a change to a stack manifest), and a second pull request that changes one is refused with the instance and the holder named, its state left as the first applied it
• PolicynonePolicy, AtmosNo check recorded.
• DriftnoneDrift, AtmosNo check recorded.The drift pull request is refused: a live value belongs in the stack vars or the component.
• Chat and notifynoneChat and notify, AtmosNo check recorded.
• Reports and visibilitynoneReports and visibility, AtmosNo check recorded.
• ModulesnoneModules, AtmosNo check recorded.Rollouts are refused: every instance of a component shares its files, so no wave can move a pin alone.
• State and migration1provenState and migration, Atmos1 check, proven.
  • each Atmos instance plans and applies in the Terraform workspace Atmos names for it, never default: the instances of one component in two stacks keep their own states, and plan no change after the apply
• Agents and pull request environmentsnoneAgents and pull request environments, AtmosNo check recorded.A copy per pull request is refused: the stack backend and workspace name the state of an instance.
• Setup and runtime3provenSetup and runtime, Atmos3 checks, all proven.
  • atmos.version in terragucci.yml is the Atmos release every job installs
  • oidc.roles by stack glob gives the instances of each Atmos stack roles of their own: config check lists each role with the states of its stack, and each instance plans and applies as the role of its stack
  • config check and init refuse the drift pull request of an Atmos repo in the same words, about the vars of the stack, never synth; respond tips proposes lock files for the components and a canary of instances

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

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

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

You can count on

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

Then read

Tasks

Use Atmos

Background

Waves and approvals

Details

terragucci.yml keys