Forgeplane runs and execution intents

A Forgeplane run is one execution intent against an instance. It captures the requested operation and resolved context. Plan promotion creates a new linked apply run. Requeue is different: it retries the same eligible run under the same run ID.

Choose an operation

Terraform and OpenTofu runs support planning and state-changing operations:

Operation	Purpose
plan	Create a reusable plan artifact for review and promotion.
apply	Apply an approved plan artifact.
destroy	Plan or perform removal of resources managed by the instance.
plan-only	Inspect proposed changes without producing a reusable apply artifact.
preview	Show proposed changes without writing state.
teardown	Remove the instance’s managed resources and clean up its workspace.

Ansible is execute-only. An Ansible instance uses execute and does not enter the Terraform/OpenTofu plan-to-apply promotion flow.

Run lifecycle

pending_approval is a run status, not an approval-record status.

A pending_approval run can enter queued after approval. A queued run enters running. A canceled running run passes through canceling while its worker stops the tool. A running run can end as succeeded, failed, canceled, or timed_out. An eligible failed, canceled, or timed_out run can requeue the same run ID to queued.

Status	Meaning
pending_approval	An execution intent is waiting for an approval decision.
queued	The coordinator is waiting for an eligible worker.
running	A worker is executing the operation.
canceling	A cancel was requested; the worker is stopping the tool, and the run ends with the attempt’s outcome.
succeeded	The operation completed successfully.
failed	Execution failed.
canceled	The run was canceled. For a run that was executing, the worker stopped the tool and reported the outcome first.
timed_out	Execution exceeded its deadline.

Plan promotion and approval

A successful plan remains a succeeded plan. Promoting it creates a new linked apply intent. If approval is required, the new run starts as pending_approval; approval moves that intent toward execution without rewriting the source plan.

The decision is stored on a separate approval record linking the requester, reviewer, decision, source plan, and promoted intent. Both runs retain their own operation and status history. See Approval workflows for the review sequence.

Inputs, secrets, and managed state

At creation, the coordinator resolves and packages non-secret inputs and approved secret-catalog bindings into the execution context sent to the worker. Inline values are not accepted for schema paths marked as secret.

Terraform and OpenTofu runs can use Forgeplane-managed state. Each run captures the state object and base generation at admission so a stale writer cannot silently replace newer state.

Evidence and events

The coordinator emits lifecycle events such as approval-pending, cancellation, and requeue. Requeue is allowed only from failed, canceled, or timed_out; it moves the existing run back to queued, clears its prior assignment, output, error, and execution timestamps, and keeps the original operation and execution snapshot. Workers stream logs while a run is active. A successful plan can publish the exact plan artifact later referenced by its promoted apply intent.

See Run operations for streaming, cancellation, requeue, artifacts, and timeout behavior.

For dependent delivery across multiple template runs, see Assemblies. For external lifecycle notifications, see Webhooks and the Webhook event reference.