VCS Connections

VCS integrations connect Forgecroft to your version control system, enabling automatic plan triggers on pushes and pull requests.

Provider Types

The provider is auto-detected from source_repo_url if not explicitly specified.

GitHub App Integration

The recommended way to integrate with GitHub is through the Forgecroft GitHub App:

1. Install the GitHub App on your organization or repository
2. After installation, Forgecroft creates a VCS integration record automatically
3. The integration uses installation tokens — no personal access tokens needed

What the GitHub App Provides

• Push webhooks — automatic plan triggers on pushes
• Pull request webhooks — plans on PR open, synchronize, and reopen
• Commit statuses — pending/completed status on commits
• PR comments — plan output posted as a comment on the PR
• Path filtering — only workspaces whose source_root matches changed paths are triggered

Token-Based Integration

For non-GitHub providers (or if you prefer not to use the GitHub App), store a Git token:

POST /vcs-integrations/{id}/secrets
{ "git_token": "ghp_..." }

Token-based integrations are rejected for GitHub App integrations — those use installation tokens through the GitHub App flow.

Scoping

VCS integrations can be scoped to:

• Organization level — available to all projects and workspaces in the org
• Project level — available only to workspaces within a specific project

Project-scoped integrations are created at POST /projects/{projectId}/vcs-integrations.

Path Filtering

When a push or PR webhook fires, Forgecroft filters workspaces based on changed paths:

1. For each changed file, check if it falls within a workspace’s source_root
2. Only matching workspaces are triggered
3. extra_checkout_paths are also considered for matching

If a PR has more than 300 changed files, Forgecroft triggers all matching workspaces as a safe fallback.

PR Matching

For pull request events, Forgecroft matches workspaces by:

1. Explicit pr_base_branch match (if set on the workspace)
2. Fallback to source_branch match

Related API Endpoints

• POST /vcs-integrations — Create an org-scoped VCS integration
• POST /projects/{projectId}/vcs-integrations — Create a project-scoped integration
• GET /vcs-integrations — List VCS integrations
• GET /vcs-integrations/{id} — Get a single integration
• PATCH /vcs-integrations/{id} — Update an integration
• DELETE /vcs-integrations/{id} — Delete (409 if workspaces reference it)
• POST /vcs-integrations/{id}/secrets — Store a Git token