Connect a known SourceCraft repository so CodeGraph can update its CPG after a push and prepare merge-request reviews from webhook events. During onboarding, CodeGraph builds metadata from the supplied repository name, clone URL, branch, and external ID. This onboarding path uses explicit coordinates rather than provider API discovery.
Integration capabilities
| Capability | Current support |
|---|---|
| Repository metadata lookup through provider API | Explicit repository coordinates |
| Branch HEAD lookup during onboarding | No |
| Namespace repository listing or bulk discovery | No |
| Inbound push and merge-request webhook | Yes |
| Review comment publication | Yes through a generic review snapshot job |
Set the repository name and branch when connecting it. Supply the import parameters for a custom clone URL or external identifier when needed.
Connect and import
Run these commands in PowerShell from the CodeGraph source repository root. Install the project
Python environment and configure the server first. Choose an existing access group:
the connection and import will belong to that group. Replace PROJECT/REPOSITORY with your value.
Import creates or finds the repository project and prints its name.
The examples use the default group. To use another group, add --group "<group-name>"
to every command. --sync-mode webhook selects repository-event synchronization;
without it, import uses manual mode.
python -m src.cli repos connect-provider --name sourcecraft-main --provider sourcecraft --base-url https://sourcecraft.yandex.cloud --host sourcecraft.yandex.cloud
python -m src.cli repos provider-health --connection sourcecraft-main
python -m src.cli repos import --connection sourcecraft-main --repo 'PROJECT/REPOSITORY' --default-branch main --sync-mode webhook
python -m src.cli repos status
After creating the connection, the CLI prints Created provider connection: sourcecraft-main.
For a successful import, find Imported repository … into project …, Binding id:,
Mirror:, and Heads: repo=… cpg=…. Keep the binding ID to follow webhook jobs.
For a private repository, pass the token through the connect-provider command’s
--token parameter, using the value supplied by your organization’s protected secret channel.
Do not use namespace bulk import: the adapter cannot list SourceCraft repositories. For a
nonstandard clone address, add --clone-url; for a stable provider identifier, add
--external-id. Private access and review publication require a token supplied through the
customer’s protected secret channel.
Configure the webhook
Set the delivery URL to the full HTTPS address of your CodeGraph API followed by the path below, for example https://codegraph.customer.example/api/v1/webhooks/sourcecraft. Replace the domain with an address the event sender can reach. Select push and merge request events.
POST /api/v1/webhooks/sourcecraft
Set SOURCECRAFT_WEBHOOK_SECRET in CodeGraph and configure
X-SourceCraft-Signature at the provider. CodeGraph verifies the request signature.
X-SourceCraft-Timestamp is optional. When the provider sends it, CodeGraph checks
the event’s age against the configured time window. Protect the endpoint with TLS
and ingress rules.
Read the body of the 202 Accepted response, then inspect the job and repository state.
accepted means that the event was accepted for processing. For skipped, read the reason
in detail.reason: for example, the repository has no binding (repository_not_bound),
the binding is inactive (binding_inactive), or the branch is outside the configured scope.
For a push, detail.ingest_status=deduplicated identifies a repeated delivery;
follow the job referenced by job_id. Check import completion and graph readiness
in the repository state after the job has been processed.
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.
Review publication and status
Shared bindings and review snapshots are exposed below:
/api/v1/integrations/repositories
POST /api/v1/integrations/repositories/review-snapshots/{snapshot_id}/rerun
Set publish_review only when a comment should be posted to the target merge request. Publication
uses the connection token and stores its own status, reason, category, and error. After the job, confirm
the published status and the actual comment on the merge request.
Authorized runtime operators can inspect:
GET /api/v1/admin/runtime/webhooks/status/{project_id}
Recovery and security
- If the repository coordinates are wrong, archive the binding and import it again with the corrected values.
- Replay only the identified failed sync or review job.
- Keep provider tokens, webhook secrets, signatures, and timestamps out of logs.
- Keep TLS verification enabled. Use the connection’s
--ca-bundle-pathfor a private CA. - Treat merge-request content as untrusted before analysis or LLM processing.
Help and troubleshooting
- Connection and import parameters: CLI guide.
- Authentication, bindings and review jobs: REST API.
- Project preparation and import verification: project import.