GitHub

Connecting GitHub lets 4RGE read repositories, open pull requests, and react to events for cloud agents and automations. The GitHub integration is the most complete source-control integration today — required for repository-scoped cloud runs and webhook-driven automations.

Connecting

1. Install the GitHub app

   From the Integrations page in the dashboard, install the 4RGE GitHub app on your organization or personal account.

2. Grant repository access

   Choose which repositories 4RGE may access — all repositories, or a selected set. Start with a minimal set and expand as teams onboard.

3. Confirm the connection

   The Integrations page shows connection status once installation completes. The agents API reports installation health at /api/github/app/status.

4. Sync repositories

   Trigger a repository sync so branches and metadata appear in the Agents workspace picker. In production this happens automatically; locally it may require the Supabase service role key (see Troubleshooting).

Dashboard connect flow

From Dashboard → Integrations, GitHub is the only source-control provider with a live connect path today. Clicking Connect calls /api/github/app/connect, which verifies your org scope, checks for an existing installation in x4rge_github_installations, and redirects to the GitHub App install URL. After GitHub redirects back to /api/github/app/callback, 4RGE syncs repositories into x4rge_repositories and records a github.installation.sync audit event.

Repository sync and recovery

Repository metadata syncs automatically on install, on installation_repositories webhooks, and when an operator calls the manual sync endpoint:

curl -X POST "https://agents-api.4rged.ai/api/github/installations/sync" \
  -H "Authorization: Bearer <session-access-token>" \
  -H "Content-Type: application/json" \
  -d '{ "organizationId": "org_abc123", "installationId": 12345678 }'

If repos are missing in the Agents workspace picker after a successful install, run manual sync and confirm the GitHub app has access to those repositories in GitHub's app settings.

What it enables

Webhook events

4RGE receives GitHub webhooks at the agents API and matches them to automations scoped to the repository:

API endpoints

Install and manage the GitHub app through the agents API (session-authenticated, org-scoped):

# Check installation status
curl "https://agents-api.4rged.ai/api/github/app/status?organizationId=org_abc123" \
  -H "Authorization: Bearer <session-access-token>"
 
# List connected repositories
curl "https://agents-api.4rged.ai/api/github/repositories?organizationId=org_abc123" \
  -H "Authorization: Bearer <session-access-token>"
 
# List branches for a repository
curl "https://agents-api.4rged.ai/api/github/repositories/42/branches?organizationId=org_abc123" \
  -H "Authorization: Bearer <session-access-token>"

Start a cloud run that opens a PR when complete:

curl -X POST "https://agents-api.4rged.ai/api/agent-runs/org_abc123/run_xyz/github/pull-request" \
  -H "Authorization: Bearer <session-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "fix: resolve flaky auth test",
    "body": "Automated fix from cloud agent run run_xyz",
    "base": "main"
  }'

Permissions model

Operator checklist

• GitHub app installed on the correct org/account
• Repository allowlist matches teams using cloud agents
• Webhook deliveries succeed (check Sentinel or operations summary)
• Branch protection rules allow bot PRs or require human review as intended
• Secrets for private submodule access configured in cloud agent environment