A workspace connects your infrastructure code to cloud credentials, a state backend, and an execution environment. Each workspace runs independently.
Required Fields
| Field | Type | Description |
|---|---|---|
name | string | Human-readable workspace name |
project_id | UUID | The project this workspace belongs to |
Source Configuration
| Field | Type | Description |
|---|---|---|
source_repo_url | string | HTTPS URL of the Git repository |
source_branch | string | Branch to run plans against |
source_root | string | Directory within the repo (default: /) |
source_repo_url and source_branch must both be set or both omitted. The URL is normalized before storage.
Tool Configuration
Forgecroft resolves the tool type and version through an inheritance hierarchy:
Workspace → Project → Organization
If a workspace doesn’t specify a tool, it inherits from its project. If the project doesn’t specify one, it inherits from the org default.
| Field | Type | Description |
|---|---|---|
tool_type | string | opentofu, terraform, pulumi, or crossplane |
tool_version | string | Specific version, validated against the tool type |
You can override the tool at the workspace level even if the project has a default.
Execution Target
| Value | Description |
|---|---|
managed | Forgecroft runs the plan in its secure environment (default) |
agent | A Forgecroft Agent in your environment claims and runs the plan |
See the Execution Modes guide for when to use each.
Optional Fields
| Field | Type | Description |
|---|---|
| vcs_integration_id | UUID | VCS integration for webhooks and PR comments |
| credential_config_ids | UUID[] | Cloud credentials for the provider |
| state_backend_config_id | UUID | State backend (S3 or GCS) |
| state_backend_credential_config_id | UUID | Credentials for the state backend |
| state_encryption_config_id | UUID | Encryption key for state at rest |
| state_key | string | Explicit state path (auto-generated if blank) |
| var_files | string[] | .tfvars file paths |
| auto_plan | bool | Plan automatically on pushes |
| auto_apply | bool | Apply automatically after successful plan |
| pr_comments_enabled | bool | Post plan output as PR comments |
| allow_pr_apply | bool | Allow apply from PR-triggered plans |
| require_approval | bool | Require approval before apply |
| min_approvals | int | Minimum approvals needed (min: 1) |
| deletion_protected | bool | Prevent workspace deletion |
| extra_checkout_paths | string[] | Additional paths to include in sparse checkout |
| extra_egress_hosts | string[] | Additional hosts allowed for egress (agent mode) |
| policy_webhook_url | string | Webhook for external policy evaluation |
| tags | string[] | Up to 50 tags, each ≤64 chars |
| attributes | object | User-defined key-value pairs for governance targeting |
Admin-Only Fields
These fields require workspace admin access to modify:
project_id, tool_config_id, vcs_integration_id, state_backend_config_id, state_backend_credential_config_id, state_encryption_config_id, execution_target, deletion_protected, auto_apply, require_approval, min_approvals, allow_pr_apply, credential_config_ids
Field Validation
tags: max 50, each ≤64 chars, no empty stringssource_root: defaults to/, must be a valid pathpolicy_webhook_url: must be a valid URL if providedmin_approvals: must be ≥ 1 when set
Related API Endpoints
POST /workspaces— Create a workspaceGET /workspaces— List workspaces (filtered by your access)GET /workspaces/{id}— Get a single workspacePATCH /workspaces/{id}— Update workspace fields