Skip to content
Forgeplane Docs

Terraform and OpenTofu approval workflows

Forgeplane approval workflows put an explicit review decision between a successful Terraform or OpenTofu plan and its apply intent. The approvals.enabled feature gate controls the workflow per environment. When review is required, the promoted apply waits for an authorized decision instead of executing immediately.

Workflow at a glance

Section titled “Workflow at a glance”
  1. A plan run succeeds and stores its plan artifact.
  2. Promotion creates a new linked apply intent; the source plan remains succeeded.
  3. The promoted intent enters pending_approval when the environment requires review.
  4. Forgeplane creates a separate approval record for the intent.
  5. An authorized reviewer approves or rejects the request.
  6. Approval queues the apply intent, which uses the exact reviewed artifact.
  7. The resulting run retains its status, logs, result, and audit links.

pending_approval is a run status. The review decision belongs to the approval record.

Configure and use the gate

Section titled “Configure and use the gate”

Use an environment boundary when approval policy differs between deployment targets. A common pattern is:

  • development allows fast feedback without an apply review;
  • staging requires an explicit review before apply;
  • production restricts credentials, workers, and reviewers and requires approval before apply.

The approval gate does not rewrite the environment or the source plan. It controls whether the promoted execution intent can enter the queue. See Environments and Feature gates for policy scope and precedence.

Approval record statuses

Section titled “Approval record statuses”
Status Meaning
pending Awaiting a reviewer decision.
approved The execution intent is authorized to continue.
rejected The reviewer denied the request. An operator message is optional; Forgeplane records rejected when it is omitted.
applied The approved intent completed successfully.

Rejecting a request does not alter the successful source plan or queue the execution intent. Change the inputs or definition, create new evidence, and submit a new promotion when appropriate.

Permissions and separation of duties

Section titled “Permissions and separation of duties”
Action Permission
Create a run and request approval run:create
Approve or reject a request run:approve

Self-approval is disabled by default. An explicit project assignment for run.approvals.self_approval.enabled overrides the system default; when no project assignment exists, the system setting is the fallback. Even when the effective policy permits self-approval, the requester must also have run:approve. Approval requires a reason, the matching pending-run ID, and acknowledgement of irreversible impact. The web form pre-populates that ID, while the backend verifies the submitted value. A rejection message is optional; when omitted, Forgeplane stores the fallback reason rejected. Platform permissions are still evaluated together with organization membership, team scope, resource ownership, lifecycle state, and other applicable policy. See Permissions and roles for the layered authorization model.

Integrity and audit chain

Section titled “Integrity and audit chain”

The promoted run links the source plan, approval ID, requester, reviewer, inputs, and execution context. Before apply, Forgeplane verifies that the plan artifact digest matches the reviewed artifact and that the apply runs the same Terraform or OpenTofu release that produced the plan. A mismatch fails closed and requires new evidence; it does not silently apply a different plan or use a different tool release.

The source plan remains an immutable successful record. Promotion and approval create linked follow-up intent rather than changing the source run into an apply run. Run operations describes promotion, artifacts, logs, cancellation, and requeue behavior.

What approval does not do

Section titled “What approval does not do”

Approval is not a general authorization bypass or an instant rollback:

  • it does not grant a principal permissions it does not already have;
  • it does not change the reviewed plan after the decision;
  • it does not turn a failed or canceled run into a successful one;
  • it does not rewind managed-state history;
  • it does not make Ansible use Terraform/OpenTofu plan/apply promotion.

Other gated mutations, including Selective Undo, use the same approval mechanism while retaining their own evidence and operation-specific rules.

Section titled “Related workflows”