Dependencies & Promotion

Workspace dependencies let you model relationships between infrastructure components and automate promotion through environments.

Dependency Types

Adding Dependencies

POST /workspaces/{id}/dependencies
{
  "depends_on_id": "workspace-uuid",
  "dependency_type": "after",
  "auto_promote": false
}

• Cannot depend on yourself (400 error)
• Cycle detection prevents circular dependencies (409 error)
• Dependencies are upserted — updating an existing edge changes dependency_type and auto_promote

Auto-Promote

When auto_promote is true, a successful apply on the upstream workspace automatically triggers a plan on the downstream workspace with trigger type promotion.

This is how Stacks create promotion graphs: when you define dev.promote_to = ["staging"], Forgecroft creates a dependency edge with auto_promote: true.

Auto-promote and auto-apply: If the downstream workspace has auto_apply: true, the promoted plan will automatically apply after governance passes. This enables fully automated promotion chains (e.g., apply in dev → auto-plan staging → auto-apply staging → auto-plan prod).

PR-triggered applies do not cascade. Auto-promote only fires for non-PR applies. This prevents pull request workflows from accidentally promoting changes through the graph.

Listing Dependencies

View what a workspace depends on:

GET /workspaces/{id}/dependencies

View what depends on a workspace (downstream consumers):

GET /workspaces/{id}/dependents

Manual Promotion

Trigger plans for all downstream workspaces:

POST /workspaces/{id}/promote

Optionally promote only specific downstreams:

POST /workspaces/{id}/promote
{ "workspace_ids": ["workspace-uuid"] }

Promotion creates queued plan runs with trigger: "promotion". Each downstream workspace is checked for trigger permission — workspaces where you lack trigger access are silently skipped.

Removing Dependencies

DELETE /workspaces/{id}/dependencies/{dependsOnId}

Use Cases

Environment Promotion

networking-dev → networking-staging → networking-prod

After applying networking changes in dev, promote to staging for validation, then to production.

Resource Dependencies

database → api → frontend

The API workspace depends on the database workspace. The frontend workspace depends on the API workspace.

Stacks

When you create a stack with promote_to, Forgecroft automatically creates the dependency graph. See the Stacks guide for details.

Related API Endpoints

• POST /workspaces/{id}/dependencies — Add a dependency
• GET /workspaces/{id}/dependencies — List dependencies
• GET /workspaces/{id}/dependents — List downstream consumers
• DELETE /workspaces/{id}/dependencies/{dependsOnId} — Remove a dependency
• POST /workspaces/{id}/promote — Trigger plans for downstream workspaces