Run approvals

When approval is needed

A plan and apply run reaches Awaiting approval when its plan has changes and policy checks allow it to continue. StackShip doesn’t support auto-apply.

Approval isn’t needed for:

• plans with no changes — the run finishes without an apply;
• plan only and speculative runs — they never apply.

Who can approve

Owners and admins can approve, discard, and cancel runs. Members can start and view runs but can’t approve them. See Roles and permissions.

Approve a plan

1. Open the run from Runs or from the workspace.
2. Review the stage counts and the Plan changes list. Expand the Plan stage to read the full log, and the Policy stage to read any findings.
3. Select Approve plan in the approval bar.

If the plan destroys at least one resource, you’re asked to confirm the create, change, and destroy counts before approving.

The approval applies only to the plan you reviewed. If the plan, policy result, or workspace state changes before you approve (for example, another run updates the state), the approval is rejected and you’re asked to reload the page.

From the CLI, tofu apply prompts for approval in your terminal. Answer there or approve in the dashboard.

Discard a plan

1. Select Discard run in the approval bar.
2. Enter a reason.
3. Select Confirm discard.

The run ends as Discarded. The reason is saved in the audit log.

Cancel a run

Select Cancel run in the run header and confirm. You can also cancel from the API, the MCP server, or the OpenTofu CLI (press Ctrl+C during tofu apply). What happens next depends on how far the run got:

• Before the apply starts (planning, policy checks, or waiting for approval), the run stops right away and ends as Canceled.
• During the apply, OpenTofu finishes the resource changes in progress, saves state, and stops. This can take up to 15 minutes; after that, StackShip stops it. If the apply finishes first, the run ends as Applied. Otherwise it ends as Apply interrupted and needs recovery before the workspace accepts new runs.

Force cancel

While a cancel is in progress during an apply, the run header shows Force cancel. It stops OpenTofu immediately. Resources being changed may be left out of state, so the run ends as Apply interrupted and needs recovery. Force cancel is available only after a regular cancel; it can’t replace it.

Approval deadline

You have seven days to approve or discard a plan; the run page shows the exact deadline. After that the run becomes Expired and can’t be approved. Push to the tracked branch or run tofu apply again to create a new plan.

Blocked by policy

If a soft-mandatory policy fails, Approve plan stays unavailable until someone with permission records an override in the Policy stage. A hard-mandatory failure can’t be overridden. See Policy sets.

Who decided

After a decision, the Approval stage shows “Approved by”, “Discarded by”, or “Canceled by” with the person and time. Every decision is also recorded in the audit log.

API

Approve and reject requests must include the approval_binding fields returned by GET /v1/runs/{run_id}/review (plan_digest, dependency_bundle_digest, predecessor_state_version_id, predecessor_state_digest, policy_evaluation_id, and policy_result_digest), so an API approval applies only to the plan you read. Send an Idempotency-Key header to retry safely. A force cancel sent when no cancel is pending, or when the run isn’t applying, returns 409 RUN_FORCE_CANCEL_NOT_AVAILABLE.

Canceling or discarding a run that someone already canceled or discarded succeeds and changes nothing; the first decision is kept.

Next steps

• Run lifecycle
• Policy sets
• Audit log