Forgeplane run operations

A run is one execution intent against an instance. The coordinator admits and schedules it; an eligible worker executes the operation. Promotion creates a new linked apply run, while requeue retries the same eligible run. See Runs and execution intents for the run model and lifecycle.

Choose an operation

Operation	Tool support	Behavior
plan	Terraform, OpenTofu	Produces a reusable plan artifact for review and promotion.
apply	Terraform, OpenTofu	Applies the exact promoted plan artifact.
destroy	Terraform, OpenTofu	Removes managed resources through a state-changing run.
plan-only	Terraform, OpenTofu	Inspects changes without producing a reusable apply artifact.
preview	Terraform, OpenTofu	Shows proposed changes without writing state.
teardown	Terraform, OpenTofu	Removes managed resources and cleans up the instance workspace.
execute	Ansible	Executes the Ansible workload. Ansible does not use plan/apply promotion.

Follow the lifecycle

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

Status	Meaning
pending_approval	A new execution intent is waiting for its approval decision.
queued	The run is waiting for an eligible worker.
running	A worker is executing the operation.
canceling	A cancel was requested while a worker was executing the operation. The worker is stopping the tool.
succeeded	Execution completed successfully.
failed	Execution failed.
canceled	The run was canceled before successful completion.
timed_out	Execution exceeded its deadline.

An execution attempt can also become unresolved while its Run remains running. This means the worker crossed the execution fence but Forgeplane cannot establish a terminal outcome. Forgeplane does not automatically replay the operation. Follow Recover an unresolved execution before canceling or requeueing it.

Promote a plan

Promotion creates a new apply intent linked to a successful plan. The source plan remains succeeded; Forgeplane does not change it into an apply run.

When approval is required, the new intent has status pending_approval and a separate approval record holds the decision. Approval queues that intent. The apply run references the reviewed artifact and verifies its SHA-256 digest before use. See Approval workflows for the review sequence.

Stream logs

The SSE endpoint is a UI-oriented stream whose component events can contain HTML; it is not a JSON log-event protocol. Machine clients should poll GET /api/v1/runs/{id} and read persisted JSON logs at GET /api/v1/runs/{id}/logs. See the API observation options for the supported client boundary.

Run logs are bounded. A single log line longer than 256 KiB is truncated and ends with a [forgeplane truncated N bytes of log line] marker. Each run stores at most 128 MiB of log text or 1,000,000 entries from its worker. Past either limit, Forgeplane stores one log limit reached warning and does not store later output from that run; the run itself continues and its outcome is unaffected.

Cancel a run

A queued or pending_approval run is canceled at once: it becomes canceled, loses its worker assignment and is never scheduled. The cancel request returns 200.

A running run first becomes canceling, and the cancel request returns 202. The worker receives the request with its next heartbeat, which is every 5 seconds by default (worker_heartbeat_interval_seconds). For Terraform and OpenTofu, it then sends the tool an interrupt (SIGINT), as Ctrl-C does in a terminal. The tool finishes its in-flight operations, saves its state and releases its lock. If the tool is still running after 60 seconds, the worker force-stops it. Ansible and plugin commands are stopped at once.

The run then ends with its attempt’s outcome. That is normally canceled, or timed_out if the job deadline passed first. If the tool had already finished successfully, the run ends succeeded. Repeating the cancel request returns 202 and changes nothing.

A run whose attempt is unresolved has no live worker to stop. Canceling it ends the run at once; see Recover an unresolved execution.

Requeue a run

Requeue retries the existing run under the same run ID. It is allowed only when the run is failed, canceled, or timed_out. A successful request moves that run back to queued, clears its prior worker assignment, output, error, start time, and completion time, and records fresh trace context. It keeps the original operation, inputs, execution snapshot, and run relationships.

Requeue does not create a new historical run record. Capture any terminal evidence that must remain separately accessible before requeueing, then review current worker capabilities, authorization, quota, template availability, pre-run resolvers, and managed-state constraints. A failed eligibility or admission check leaves the terminal run unchanged.

For an unresolved execution, investigate first and cancel explicitly before requeueing. Requeue closes the old attempt with its unresolved evidence intact and creates a new attempt attributed to the requeueing operator. It can repeat an external effect.

Check plan artifacts

A successful plan uploads its binary plan artifact to the configured artifact backend. Forgeplane records its digest and enforces the configured size limit. Promotion keeps the plan, approval, and apply intent linked in one audit chain.

Before Terraform or OpenTofu starts, the worker reports the tool family and release it is about to run, and Forgeplane records it for that attempt. A plan artifact keeps the family and release that produced it. Only that same family and release can apply it: if the apply is pinned to another release, or the plan has no recorded producer, the apply does not start and you need a fresh plan. When no default tool version is configured, the apply uses the release that produced the plan.

Review execution context

The worker receives resolved non-secret inputs, coordinator-materialized secret payloads, the requested tool version, and an execution fingerprint. Managed-state runs also receive the state object identity, base generation, and state status captured at admission.

See Managed state for storage and recovery behavior and Secret management for secret delivery.

Apply timeout precedence

The first configured value wins:

1. run-level override;
2. template default;
3. job_timeout_default_minutes system setting.

When the deadline expires, the worker stops the process and the run becomes timed_out.

Operator checklist

Before promoting, requeueing, or canceling a run, verify:

• the run status and operation;
• the linked plan or source run, if any;
• current inputs, approvals, and worker capabilities;
• the plan artifact digest and size, when applying a plan;
• the managed-state object and base generation, when state is managed.