Promotion Graph

How Promotion Works

The promote_to field on each environment defines a directed graph of promotion paths:

{
  "environments": [
    { "name": "dev",     "promote_to": ["staging"] },
    { "name": "staging", "promote_to": ["prod"] },
    { "name": "prod",    "promote_to": [] }
  ]
}

This creates workspace dependency edges with auto_promote: true:

dev ──(auto)──→ staging ──(auto)──→ prod

Auto-Promote vs Manual Promotion

When auto_promote is true on a dependency edge:

• After a successful apply on the upstream workspace, a plan run is automatically queued for the downstream workspace
• The downstream run has trigger: "promotion"

When auto_promote is false:

• No automatic promotion occurs
• You must manually trigger promotion with POST /workspaces/{id}/promote

Promotion Flow

1. A run completes successfully on the upstream workspace (e.g., myapp-dev)
2. Forgecroft checks for downstream workspaces with auto_promote: true
3. For each downstream workspace, it creates a queued plan run
4. The downstream run appears in the run list with trigger: "promotion"
5. The downstream workspace processes the run according to its own settings (auto-apply, governance, etc.)

Manual Promotion

Promote changes from a workspace to all its downstreams:

POST /workspaces/{id}/promote

This creates queued plan runs for all non-auto dependents. Optionally promote only specific downstreams:

{ "workspace_ids": ["workspace-uuid"] }

Promotion Graph Visualization

For a stack with dev → staging → prod:

Plan in dev
  ↓ (apply succeeds)
Auto-plan in staging
  ↓ (review, approve, apply)
Auto-plan in prod
  ↓ (review, approve, apply)
Deployed to prod

Fan-Out Promotion

A single environment can promote to multiple environments:

{
  "name": "dev",
  "promote_to": ["staging-us", "staging-eu"]
}

This creates edges from dev to both staging environments simultaneously.

Viewing Promotion Status

Get stack detail to see the status of each environment:

GET /stacks/{id}

Response includes each environment’s workspace name, order, auto_promote flag, and latest run status.

Related

• Dependencies & Promotion — Workspace-level dependency management
• Managing Stacks — CRUD operations on stacks