GitHub SCM

PRs, reviews, and CI status via the gh CLI. Optional webhook for real-time events.

Slot: scm · Name: github

macOSSupported

LinuxSupported

WindowsSupported

The default SCM. Uses gh for PR + review + CI polling. Optional webhook support for reduced poll latency.

Setup

gh auth login

agent-orchestrator.yaml

scm: github
projects:
  myproject:
    repo: owner/repo

Webhook endpoint

AO's dashboard receives webhook events at:

POST /api/webhooks

The absolute URL is https://<your-ao-host>/api/webhooks. To expose your local dashboard publicly, see Remote access.

GitHub repo settings

In your GitHub repo go to Settings → Webhooks → Add webhook:

Payload URL: https://<your-ao-host>/api/webhooks
Content type: application/json
Secret: the value of your secretEnvVar environment variable
Events: Pull requests, Push, Workflow runs, Pull request reviews, Check suites

Config

scm: github
projects:
  myproject:
    repo: owner/repo
    scm:
      webhook:
        secretEnvVar: GITHUB_WEBHOOK_SECRET    # env var holding the HMAC secret

Full webhook.* sub-object:

Field	Default	Description
`enabled`	`true`	Enable or disable webhook processing
`path`	`/api/webhooks`	Override the receive path
`secretEnvVar`	—	Name of the env var holding the HMAC secret
`signatureHeader`	`x-hub-signature-256`	Header carrying the HMAC-SHA256 signature
`eventHeader`	`x-github-event`	Header carrying the event type
`deliveryHeader`	`x-github-delivery`	Header carrying the delivery UUID
`maxBodyBytes`	unlimited	Reject payloads larger than this (bytes)

Signature: HMAC-SHA256 over the raw request body. AO compares the computed digest against the value in x-hub-signature-256 using a constant-time comparison.

Polling is still active as a fallback — webhooks are a latency optimisation, not a hard dependency.

Batch enrichment (performance)

On every poll cycle AO issues a single batched GraphQL query that fetches PR state, CI check results, review decisions, and merge readiness for all active sessions in a project at once. This replaces N × 3 REST calls with a single request.

For rate-limit debugging: even with dozens of concurrent sessions, AO stays well under GitHub's primary rate limit. If you do hit limits, the batch enricher backs off and queues — see Troubleshooting.

Rate limits

AO paces gh calls per-project. If you hit limits anyway, batch-enrichment backs off and queues — see Troubleshooting for the diagnostic steps.