GitHub App Integration

Installation

1. Install the Forgecroft GitHub App on your organization or repository
2. After installation, you are redirected back to Forgecroft which creates a VCS integration record
3. The integration is ready — webhooks are configured automatically

What the GitHub App Provides

Push Webhooks

When you push to a branch, Forgecroft:

1. Receives the webhook
2. Matches workspaces by source_branch and source_root
3. Creates a changeset and queues a plan run

Pull Request Webhooks

On PR open, synchronize, or reopen:

1. Forgecroft fetches changed files from the GitHub API
2. Filters workspaces by source_root and extra_checkout_paths
3. Matches workspaces by pr_base_branch (or falls back to source_branch)
4. Creates a changeset with source_type: "git" and pr_number
5. Posts a pending commit status
6. Queues a plan run with trigger: "pr"

Commit Statuses

Forgecroft posts commit statuses for each matched workspace:

• pending — before the run starts
• success — when the plan completes
• failure — when the plan fails

PR Comments

If pr_comments_enabled is true on the workspace, Forgecroft posts the plan output as a PR comment. The comment is stale-marked on subsequent pushes.

Path Filtering

Only workspaces whose source_root (or extra_checkout_paths) matches a changed file path are triggered. This prevents unnecessary runs when unrelated files change.

For PRs with more than 300 changed files, Forgecroft triggers all matching workspaces as a safe fallback.

VCS Integration Record

After installation, Forgecroft creates a VCS integration with:

• provider: github
• installation_id: from the GitHub App installation
• source_repo_url: from the installation context

This integration can be attached to workspaces via vcs_integration_id.

Related

• VCS Connections — VCS integration management
• Webhook Handler — Technical details of the webhook endpoint