84 lines
3.0 KiB
Plaintext
84 lines
3.0 KiB
Plaintext
---
|
||
title: GitHub SCM
|
||
description: PRs, reviews, and CI status via the gh CLI. Optional webhook for real-time events.
|
||
---
|
||
|
||
<div style={{ display: "flex", alignItems: "center", gap: "0.75rem", margin: "0.5rem 0 1.25rem" }}>
|
||
<Logo name="github" size={28} />
|
||
<span style={{ fontSize: "0.8125rem", color: "var(--color-fd-muted-foreground)" }}>Slot: <code>scm</code> · Name: <code>github</code></span>
|
||
</div>
|
||
|
||
<PlatformSupport macos="full" linux="full" windows="full" />
|
||
|
||
The default SCM. Uses `gh` for PR + review + CI polling. Optional webhook support for reduced poll latency.
|
||
|
||
## Setup
|
||
|
||
```bash
|
||
gh auth login
|
||
```
|
||
|
||
```yaml title="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](/docs/configuration/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
|
||
|
||
```yaml
|
||
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](/docs/troubleshooting).
|
||
|
||
## Rate limits
|
||
|
||
AO paces `gh` calls per-project. If you hit limits anyway, batch-enrichment backs off and queues — see [Troubleshooting](/docs/troubleshooting) for the diagnostic steps.
|