PR commands

Comment on a pull request to tell teriac what to do. Every comment starts with teriac. Comment teriac help (or just teriac) for the list of commands this server allows.

Plan, apply and unlock

Comment	Does
`teriac plan`	Plan every project this PR changes
`teriac plan -p <project>`	Plan one project. `-d <dir>` and `-w <workspace>` also work
`teriac plan -p <project> -t <address>`	Plan only some resources; repeat `-t` for more
`teriac plan --destroy`	Plan a destroy
`teriac plan -p <project> --replace <address>`	Plan replacing a resource; repeat for more
`teriac plan -p <project> --refresh-only`	Plan updating the state to match what's deployed
`teriac apply`	Apply every ready project (can be turned off, see below)
`teriac apply -p <project>`	Apply one project. The Apply button does the same
`teriac apply -p <project> --override`	Apply despite enforced policy findings (only for people in `override`)
`teriac unlock`	Release this PR's locks and drop its plans

Apply always uses the saved plan, so what runs is exactly what was reviewed.

Flags

Flag	Long form
`-p`	`--project`	A project by name or folder
`-d`	`--dir`	A project by folder
`-w`	`--workspace`	A Terraform workspace
`-t`	`--target`	A resource address to target (plan)
	`--destroy`	Plan a destroy. Plan only; can't be combined with `--refresh-only`
	`--replace`	A resource address to replace
	`--refresh-only`	Plan only state updates
	`--override`	Apply despite enforced policy findings. Needs `-p`. Also covers change freezes and protected resources: it skips only the entries whose `override` list includes you
`--`		Extra arguments for Terraform, such as `-- -var=x`. Off unless the repo sets `allow_extra_args: true`

Examples

teriac plan -p live/prod/vpc -t aws_subnet.private -t aws_route_table.private
teriac plan -p live/prod/app --replace aws_instance.web
teriac plan -p live/prod/app --refresh-only
teriac plan -d stacks/orders -w staging
teriac apply -p live/prod/vpc

One project at a time

To make people apply one project at a time, set TERIAC_REQUIRE_APPLY_PROJECT=true (or require_apply_project: true for a repo in repos.yaml or its teriac.yaml). A bare teriac apply is then refused, and teriac help leaves it out.

What an apply checks

Before anything runs, teriac checks, per project:

you have the apply permission (or apply_destroy, if the plan deletes or replaces anything);
the project has its required approvals, on the current commit;
its apply_requirements are met (approved, mergeable, undiverged);
the two-person rule, if on;
no enforced policy finding is open (or you used --override);
the plan is still current: no newer commit, no Terragrunt dependency applied since, no mock outputs;
no change freeze is on;
no protected resource would be destroyed or replaced;
any extra approvals the plan's risk level needs;
the base branch hasn't changed the project's files since the PR branched, if stale_base: block;
the plan file is exactly the one that was reviewed (verify_plan).

If any check fails, teriac says which one, and nothing runs.

Terraform commands

These run on one project (-p <project>). Each needs a permission (see rules and permissions):

Comment	Needs
`teriac validate`, `providers`, `fmt`, `state list [address]`	`plan`
`teriac state show <address>`, `show`, `output [name]`	`state_read`
`teriac import <address> <id>`, `taint <address>`, `untaint <address>`	`state_write` and approvals
`teriac state rm <address>...`, `state mv <from> <to>`, `force-unlock <lock-id>`	`state_remove` and approvals

teriac state list -p live/prod/app
teriac state show -p live/prod/app aws_instance.web
teriac output -p live/prod/app
teriac import -p live/prod/app aws_s3_bucket.logs acme-logs
teriac state mv -p live/prod/app aws_instance.web aws_instance.api
teriac force-unlock -p live/prod/app 6d1c2a8e-…

What each one does

Command	Runs
`state list`	Resources in the state
`state show`	One resource's attributes, with sensitive values hidden
`output`	Output values, with sensitive values hidden
`show`	The whole current state
`validate`	`validate`: check the configuration
`providers`	The providers the project uses
`fmt`	`fmt -check -diff -recursive`: report formatting, change nothing
`import`	Bring an existing resource under Terraform
`taint` / `untaint`	Mark a resource to be replaced on the next apply, or undo it
`state rm`	Stop managing resources without deleting them
`state mv`	Rename or move a resource in the state
`force-unlock`	`terraform force-unlock`: release a stuck lock in the state backend, left by a crashed run (Error acquiring the state lock). Not the same as `teriac unlock`

Safety

Commands that edit the state directly take the project's lock, need approvals like an apply, are audited, and plan the project again straight after.
Only these commands run, and their arguments are checked (addresses, IDs, lock IDs), so nothing else (such as console or -chdir) can be passed through.
Turn direct state edits off for a repo with allow_state_changes: false.

How teriac answers

It reacts to a command it picked up (👀 by default). Change it with TERIAC_ACK_REACTION, or turn it off with none.
Each result is posted once as a new comment and never edited. With TERIAC_PROGRESS_REPLY=true it posts a spinning "Running…" reply instead and edits it into the result.
With TERIAC_COMMENT_MODE=update, plans and applies go in one comment at the top, edited in place.
Every project also gets a check run, teriac: <project>, with its result and an Apply button.
The plan comment's table has a Risk column and a ▶ Apply link per project, and notes the two-person rule in the Apply cell when it's on.

See settings for all of these.

Locks

A plan takes the lock for each project and workspace. If another PR holds it, the comment says 🔒 locked by #123 (alice); apply or unlock it there first.

Locks are released when:

the PR is applied;
someone comments teriac unlock (or teriac unlock -p <project> for one project). The PR's author and anyone with the plan permission on the project can do this; it also drops the saved plans;
the PR is merged or closed, which also deletes its checkouts and plans;
an admin releases it from the dashboard or the API. That's audited.