Forgecroft Docs
Quickstart Guides Essentials Power Agent API Reference
Core ConceptsCLI ReferenceGo SDKAuthenticationAPI KeysRoles & PermissionsCreating WorkspacesVCS ConnectionsCredentialsState BackendsExecution ModesWorkspace AttributesDependencies & PromotionStacks OverviewCreating StacksEnvironments & VarfilesPromotion GraphManaging StacksRun LifecyclePlan vs ApplyChangesetsApprovalsLogsForce UnlockDrift DetectionTroubleshootingGovernance OverviewPolicy SetsWriting RegoRego PlaygroundApproval RulesExternal ChecksGovernance PreviewGovernance TimelineManaging TeamsNotification ChannelsNotification TargetsUser PreferencesAccess GrantsAudit EventsGitHub AppSlackCredential TypesState Backends
Guides / Runs

Run Lifecycle

Every run moves through a defined set of statuses. Understanding the lifecycle helps you debug and automate.

Status Diagram

queued ──→ in_progress ──→ completed
    │           │              │
    │           │              ├──→ pending_approval ──→ completed (after auto-apply)
    │           │              │
    │           │              ├──→ pending_policy ──→ completed
    │           │              │
    │           │              └──→ rejected
    │           │
    │           ├──→ failed
    │           ├──→ timed_out
    │           └──→ aborted
    │
    └──→ (stays queued until claimed)

All Statuses

StatusTerminalDescription
queuedNoRun is waiting to be executed
in_progressNoRun is currently executing
completedYesRun finished successfully
failedYesRun finished with an error
timed_outYesRun exceeded the timeout
pending_policyNoRun is waiting for policy evaluation
pending_approvalNoRun is waiting for human approval
rejectedYesRun was rejected by governance
abortedYesRun was cancelled by a user
unlockedYesForce-unlock run completed

Run Types

TypeDescription
planProduces a plan showing what would change
applyExecutes a previously created plan
unlockReleases a stale Terraform state lock

Trigger Sources

TriggerHow it starts
manualUser clicked “Run Plan” or called the API
pushGit push webhook matched the workspace
scheduleScheduled run (cron)
prPull request webhook
promotionUpstream workspace promoted changes

Concurrency

One run at a time per workspace. Only one run can be in_progress for a given workspace. Additional runs stay in queued until the active run completes. This prevents concurrent state modifications.

Per-org concurrency for managed runs. Managed execution has a per-org limit on concurrent runner jobs (default: 3). If your org has more queued runs than this limit, they execute in order as slots free up. Large orgs with many active workspaces should expect queueing during busy periods.

Lifecycle Flow

Plan Run

  1. queued — Run is created and waiting for a runner slot
  2. in_progress — Runner claims the run on its first heartbeat and starts executing
  3. completed — Plan produced successfully
  4. Governance evaluates (if configured):
    • No violations → stays completed
    • Advisory violations → stays completed with warnings
    • Mandatory violations → transitions to rejected
    • Approval required → transitions to pending_approval

Apply Run

  1. queued — Created from a completed plan (or manually)
  2. in_progress — Runner executes the plan
  3. completed — Changes applied, changeset stamped with applied_at
  4. Auto-promotion triggers downstream workspaces (if configured)

Terminal Statuses

Once a run reaches a terminal status (completed, failed, timed_out, rejected, aborted, unlocked), it cannot be changed. To re-run, create a new run.