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

Plan vs Apply

Plans preview changes. Applies execute them. Understanding the relationship is key to safe infrastructure management.

The Plan → Apply Flow

  1. A plan run reads your current state and code, then produces a plan showing what would change
  2. The plan is stored as a binary file and parsed for resource-level changes
  3. Governance evaluates the plan (policies, approval rules, external checks)
  4. If governance passes, an apply run executes the stored plan against your infrastructure
  5. On successful apply, the changeset is marked as applied_at

Creating a Plan

POST /workspaces/{id}/runs

This creates a new changeset (with source_type: "api") and a queued plan run.

Applying a Plan

POST /workspaces/{workspaceId}/runs/{runId}/apply

Creates an apply run from a completed plan run.

Requirements

Discarding a Changeset

POST /workspaces/{workspaceId}/changesets/{changesetId}/discard

Marks a changeset as discarded, preventing any future applies. Returns 409 if the changeset is already applied or discarded.

Changeset Sources

Source TypeHow it’s created
gitPush or PR webhook triggered a plan
apiManual POST /workspaces/{id}/runs call

Idempotency Guard

Forgecroft uses an atomic CTE (Common Table Expression) to guard against concurrent discard and duplicate applies. If two users try to apply the same plan simultaneously, only one succeeds.

Drift Detection on Apply

When an apply run executes, Forgecroft verifies the plan matches the approved plan counts. If the plan has drifted (different resource counts), the apply returns 409. This prevents applying a plan that differs from what was reviewed.