Core Concepts

Hierarchy

Organization
 └── Project
      └── Workspace
           ├── Changeset
           │    └── Run (plan / apply / unlock)
           └── Stack (optional)
                └── Environment → Workspace

Concepts

Organization

The top-level boundary for access control, billing, and resource ownership. Every object in Forgecroft belongs to exactly one organization. Members have roles: owner, admin, member, or reader. Without an organization, nothing else exists.

Project

A grouping of related workspaces. Use projects to separate concerns by team, product, or region. Each project can carry its own default tool config and notification channels, so workspace authors inherit sane defaults instead of configuring each one from scratch.

Workspace

A single Terraform/OpenTofu root module — one repository path, one set of credentials, one state backend, one execution mode. This is the unit you plan, apply, and monitor. Workspaces produce runs independently, so a failure in one workspace never blocks another.

Stack

A template that stamps out one workspace per environment (dev, staging, prod) from a single definition. Stacks also define a promotion graph between those environments. Without stacks, you duplicate workspace configuration for every environment by hand.

Environment

A named slot within a stack (e.g., dev, staging, prod). Each environment becomes its own workspace named {stack}-{env} and gets a dedicated .tfvars file for environment-specific values.

Changeset

A snapshot of planned infrastructure changes produced by a plan run. A changeset can be applied (execute the changes) or discarded (prevent future applies). Changesets originate from two sources: git activity (push or PR) or the API (manual trigger). Tracking changesets separately from runs lets you audit what was proposed versus what was executed.

A state lock prevents concurrent writes to the same Terraform state file. Forgecroft acquires a lock before any run that modifies state and releases it when the run finishes. If a run crashes, the lock may remain — an unlock run type exists to clear it.

Run

A single execution of tofu plan, tofu apply, or tofu force-unlock against a workspace. Runs are the atomic unit of work. Each run has a type, a status, and a trigger source.

Drift is when real infrastructure diverges from the declared configuration. A plan run detects drift; an apply run corrects it.

Run Status

Runs move through statuses:

queued → in_progress → completed | failed | timed_out | pending_approval | rejected | aborted

Terminal statuses (completed, failed, timed_out, rejected, aborted) cannot change. A run stuck in in_progress without a heartbeat for 10 minutes is marked timed_out by an automatic sweeper.

Trigger

What caused a run to start:

• manual — a user clicked “Run” in the console or called the API
• push — a git push webhook fired
• schedule — a cron schedule triggered the run
• pr — a pull request webhook fired
• promotion — an upstream workspace in a stack completed successfully

Execution Target

Where the run executes:

• managed — Forgecroft runs it in an ephemeral container in our environment. No infrastructure on your side.
• agent — a Forgecroft Agent running in your own environment claims the run. Use this when workspaces need access to private networks or resources that cannot be reached from the managed environment.