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.
Integration capabilities
| 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 review snapshot job that publishes to the pull request |
Connect and import
Run these PowerShell commands from the CodeGraph source root with its Python dependencies
and server access configured. Replace OWNER/REPOSITORY with the repository full name.
These commands create a connection and start an import in the default group. To use another
group, add --group "<group-name>" to all four commands. --sync-mode webhook selects
repository-event synchronization; without it, import uses manual mode.
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' --sync-mode webhook
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
In the GitHub repository settings, open Settings → Webhooks → Add webhook. Set Payload URL to the full HTTPS URL of your CodeGraph API followed by the path below, for example https://codegraph.customer.example/api/v1/admin/runtime/webhooks/github. Replace the domain with an address GitHub can reach. Select Content type: application/json and keep SSL verification enabled. See GitHub webhook setup for the creation steps.
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.
What happens after delivery
CodeGraph verifies the signature, then converts the GitHub payload into a shared
repository event. For push, it reads the repository name and clone URL,
ref, before, after, and changed paths from commits. The sync queue finds
the repository binding and selects its enabled canonical tracked branch.
When no explicit tracked branches exist, the default branch acts as the canonical branch.
The queue saves the event and creates a sync job. A repeated push with the same
branch ref and after commit resolves to the existing event for that binding.
A pull_request event follows the review snapshot queue: CodeGraph captures the
request number, action, head and base branches, and their commit IDs for the review.
The receiver responds with HTTP 202 and returns status, event_type,
job_id, and detail. Use the fields below to follow the event:
| Field | Meaning |
|---|---|
status |
The result of accepting or skipping the event. |
job_id |
The associated background job ID, when a job exists. |
detail.commit / detail.changed_files |
The push’s after commit and number of changed paths. |
detail.ingest_status |
The sync queue result, such as accepted or deduplicated. |
detail.review_id / detail.action / detail.snapshot_id |
Pull-request identity, normalized action, and saved review snapshot ID. |
detail.reason |
Why an event was skipped, for example repository_not_bound, binding_inactive, or branch_not_tracked. |
For example, a push on refs/heads/main that modifies src/auth.py identifies
the new commit in detail.commit and reports detail.changed_files: 1.
Use its job_id to follow synchronization, then compare the repository HEAD
and CPG HEAD. For a pull request, retain detail.snapshot_id to reopen the review
for its recorded head and base revisions.
For ping, the receiver returns status=accepted and
detail.message=pong. For an unsupported event, it returns status=skipped and
detail.reason=unsupported_event_type.
Where to check the result
Authenticate requests as described in the REST API reference. Get binding_id from the list of accessible repository bindings: GET /api/v1/integrations/repositories/bindings. Use that ID in the routes below. For a review, use detail.snapshot_id from the webhook response.
| What to check | Request and result |
|---|---|
| Synchronization after a push | GET /api/v1/integrations/repositories/bindings/{binding_id}/sync-jobs: find the items entry whose id matches the webhook response’s job_id; inspect status, commit_sha, result, and error. |
| Current graph revision | GET /api/v1/integrations/repositories/bindings/{binding_id}: compare repository_head_sha and cpg_head_sha after the job completes. |
| PR/MR processing | GET /api/v1/integrations/repositories/review-snapshots/{snapshot_id}/jobs: inspect the saved review snapshot’s jobs. |
In job lists, check has_next. To read the next page, increase offset by the returned limit and repeat the request. Match the job ID rather than relying on the first list entry.
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.
Help and troubleshooting
See the CLI guide for repository command options and the REST API reference for server operations. If a connection or job fails, follow the troubleshooting guide.