Use this guide when CodeGraph must import GitHub repositories, keep their CPG state aligned with pushes, and create review snapshots for pull requests. It covers the GitHub-specific boundary; the shared repository lifecycle is described in Project import.
Supported contract
| Capability | Current support |
|---|---|
| Repository metadata through provider API | Yes |
| Branch HEAD lookup | Yes |
| Organization or user repository listing | Yes |
| Inbound push and pull-request webhook | Yes |
| Review comment publication | Yes through a generic review snapshot job; no dedicated GitHub route |
The implementation source is
src/project_import/repository_suite/repository_provider_adapters.py. Do not infer GitHub
features from another provider’s guide.
Connect and import
For a public repository, create a connection without placing credentials in the command:
python -m src.cli repos connect-provider --name github-main --provider github --base-url https://api.github.com --host github.com
python -m src.cli repos provider-health --connection github-main
python -m src.cli repos import --connection github-main --repo OWNER/REPOSITORY
python -m src.cli repos status
Private repositories require a provider token. The CLI exposes --token, but a literal secret
can remain in shell history or process inspection. Supply it only through the protected secret
channel used by the customer deployment, then run provider-health before import. TLS validation
is enabled by default; use --ca-bundle-path for a private CA.
Configure the webhook
Create a GitHub webhook for:
POST /api/v1/admin/runtime/webhooks/github
Subscribe to push and pull_request. Configure the same secret in GitHub and the CodeGraph
runtime as GITHUB_WEBHOOK_SECRET. GitHub sends the event name in X-GitHub-Event and the
HMAC-SHA256 signature in X-Hub-Signature-256.
The receiver returns 202 Accepted after an event has been accepted, deduplicated, or skipped for
background processing. Correlate the returned job and inspect repository status to confirm the CPG
update and review completion.
Observe and recover
The shared REST surface begins at:
/api/v1/integrations/repositories
POST /api/v1/integrations/repositories/review-snapshots/{snapshot_id}/rerun
Use it, or the matching python -m src.cli repos ... commands, to inspect bindings, sync jobs,
backlog, review snapshots, pause/resume state, and replayable failures. Authorized runtime
operators can also inspect:
GET /api/v1/admin/runtime/webhooks/status/{project_id}
A rerun publishes a GitHub comment only when publish_review is requested and a provider token is
available. Confirm the stored publication status and the comment on the pull request.
A safe recovery sequence is: check provider health, inspect the binding and job, replay only a failed job, then confirm that the repository HEAD and CPG HEAD converge. Use the job status and repository state to confirm completion after a new event.
Security boundary
- Keep provider tokens and webhook secrets outside repository files and logs.
- Keep TLS verification enabled; use a custom CA bundle for an enterprise proxy.
- Restrict the admin runtime route to operators. The webhook signature authenticates the event and the operator session authorizes separate API calls.
- Treat pull-request content as untrusted input before it reaches an LLM-backed workflow.
Source of truth
- Provider adapter:
src/project_import/repository_suite/repository_provider_adapters.py - Repository CLI:
src/cli/repo_suite/repos_parser.py - Webhook receiver:
src/api/routers/collaboration_suite/webhook.py - Generated current routes: REST API