Configuration Overview

Core concepts

Before you start clicking through the sidebar, it helps to understand the three main levels in Forgecroft.

Organization

Your organization is the top-level account boundary in Forgecroft.

It is where you manage:

• Members
• Shared infrastructure configuration
• Governance
• API keys
• Organization-wide defaults

Most teams have one organization per company or internal platform account.

Project

A project groups related workspaces together.

Use projects to separate things like:

• Production vs non-production
• Platform vs application teams
• Different business units

A project can also carry project-level settings such as:

• Members
• Default tool config
• Notification configs

Workspace

A workspace is a single infrastructure root that Forgecroft can plan and apply.

Each workspace has its own:

• Source location
• State
• Execution mode
• Run history
• Notifications

If your repository contains multiple infrastructure roots, each one should usually be a separate workspace.

How the hierarchy works

The normal model is:

1. Your team works inside one organization
2. You create one or more projects inside it
3. You create workspaces inside each project

In practice:

• Organization is where shared configuration lives
• Project is how you group related work
• Workspace is what actually runs

For most teams, the fastest path is:

1. Create a project
2. Create a workspace
3. Connect credentials, state, and source
4. Run a plan
5. Add approvals later if needed

Some sidebar sections are only visible to organization admins.

Projects

Projects are the top-level way to organize related workspaces.

From the Projects area, you can:

• Create a project
• Set its name and description
• Add or remove project members
• Choose a default tool configuration for that project
• Attach notification configs to the project

Use projects to separate environments, teams, or business domains.

Workspaces

A workspace is one infrastructure root with its own source, state, execution mode, and run history.

From a workspace and its settings page, you can configure:

• Workspace name
• Source repository URL
• Source branch
• Source root directory
• VCS integration
• Provider credentials
• State backend
• State key
• Tool configuration
• Execution mode: managed or agent
• Auto-plan on push
• Auto-apply after plan
• Notification configs
• GitHub PR comments
• Legacy workspace approvers
• Deletion protection

If you are just getting started, the important fields are source, credentials, state backend, and execution mode.

Settings

The Settings section controls organization-wide configuration.

General

Use General to view basic organization details and update the organization name.

Members

Use Members to manage access to the organization.

You can:

• Invite new members by email
• Choose each member’s role
• Update existing member roles
• Remove members
• Review pending invites

Infrastructure

Infrastructure settings define reusable building blocks that projects and workspaces can reference.

Tools

Tool configs let you define named tool and version combinations.

You can configure:

• Name
• Tool type
• Version
• Scope
• Organization default tool config

Use this to standardize which OpenTofu or Terraform version runs across your environments.

Credentials

Credential configs store reusable cloud access definitions.

You can configure:

• Name
• Credential type
• Scope
• Provider-specific secret material on the detail page

Attach credentials to workspaces instead of re-entering them repeatedly.

State Backends

State backend configs define where state is stored.

You can configure:

• Name
• Backend type
• Scope
• Bucket name
• Region
• Endpoint
• Optional backend access credentials

Workspaces then select one backend config and optionally set a workspace-specific state key.

VCS Integrations

VCS integrations connect Forgecroft to your source provider.

You can configure:

• Name
• Provider
• Installation ID when needed
• Scope
• Provider secrets or linked app installation on the detail page

Use VCS integrations for repo access, webhook-driven plans, and PR comments.

Notifications

Notification configs define where Forgecroft sends updates.

You can configure:

• Name
• Channel type
• Channel destination or hint
• Targets on the detail page

Projects and workspaces can attach notification configs as needed.

API Keys

API keys are machine credentials for automation and self-hosted agents.

You can configure:

• Key name
• Expiry

The full key is shown once when created. Store it securely.

Governance

Governance settings control how plans are evaluated and when applies need approval.

You can start simple and add this later.

Overview

The Governance overview explains how policy checks and approval flows work together.

Groups

Groups are named collections of people used for approval routing.

You can configure:

• Group name
• Description
• Group membership

Policy Sets

Policy sets let you evaluate plans against OPA/Rego rules.

You can configure:

• Name
• Description
• Enforcement mode
• Profile
• Scope
• Individual policies inside the set

Use policy sets when you want to warn on or block changes automatically.

Approval Rules

Approval rules define when a run needs human approval.

You can configure:

• Name
• Description
• Scope
• Stage
• Trigger condition
• Approver type
• Target group or org role
• Minimum approvals
• Timeout
• Timeout behavior

Use approval rules to require review for production changes, destructive changes, or other sensitive operations.

What most teams should configure first

If you want the shortest path to value, configure these in order:

1. One project
2. One workspace
3. One credential config
4. One state backend config
5. One VCS integration if needed
6. Optional notification config
7. Approval rules only after your first workspace is working