Hierarchy
Organization
└── Project
└── Workspace
├── Changeset
│ └── Run (plan / apply / unlock)
└── Stack (optional)
└── Environment → Workspace
Concepts
Organization
Your company or team. Everything in Forgecroft belongs to one organization. Members have roles: owner, admin, member, or reader.
Project
A grouping for related workspaces. Projects let you organize work by team, product, or environment. Each project can have its own default tool config and notification channels.
Workspace
A single unit of infrastructure management. A workspace points to a source repository, has credentials attached, a state backend, and an execution mode. Each workspace produces runs independently.
Stack
A multi-environment workspace template. One stack creates multiple workspaces (one per environment like dev, staging, prod) with a promotion graph between them. Each environment gets its own .tfvars file.
Environment
A named environment within a stack (e.g., dev, staging, prod). Each environment becomes its own workspace with the naming convention {stack}-{env}.
Changeset
A unit of planned change to infrastructure. A changeset is created by a plan run and can be applied (to execute the changes) or discarded (to prevent future applies). Changesets come from two sources: git (push or PR) or API (manual trigger).
Run
A single execution of a tool against a workspace. Runs have a type (plan, apply, or unlock), a status, and a trigger source (manual, push, schedule, pr, or promotion).
Run Status
Runs move through statuses: queued → in_progress → completed / failed / timed_out / pending_approval / rejected / aborted. Terminal statuses cannot be changed.
Trigger
What caused a run to start. manual (user clicked run), push (git push webhook), schedule (cron), pr (pull request webhook), or promotion (upstream workspace promotion).
Execution Target
Where a run executes. managed means Forgecroft runs it in our secure environment. agent means the run is claimed by a Forgecroft Agent running in your own environment.