GitLab integration — Documentation

Use this guide for GitLab.com or a self-managed GitLab instance. CodeGraph can resolve repository metadata, import a group, synchronize pushes, and create review snapshots for merge requests. The shared lifecycle remains in Project import.

Integration capabilities

Integration capabilities
Capability	Current support
Repository metadata through GitLab API v4	Yes
Branch HEAD lookup	Yes
Group repository listing	Yes
Inbound push and merge-request webhook	Yes
Review comment publication	Yes through a review snapshot job that publishes to the merge request

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 GROUP/REPOSITORY and GROUP with your values. Import creates or finds the repository project and prints its name.

Set --base-url to the API root and --host to the clone host:

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 gitlab-main --provider gitlab --base-url https://gitlab.example.com/api/v4 --host gitlab.example.com
python -m src.cli repos provider-health --connection gitlab-main
python -m src.cli repos import --connection gitlab-main --repo 'GROUP/REPOSITORY' --sync-mode webhook
python -m src.cli repos status

After creating the connection, the CLI prints Created provider connection: gitlab-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. Private projects require a provider token. The CLI exposes --token, but a literal secret can remain in shell history or be visible during process inspection. Supply it only through your deployment’s protected secret channel, then run provider-health before import.

Use the same connection for a bounded group import:

python -m src.cli repos bulk-import --connection gitlab-main --namespace 'GROUP' --dry-run --sync-mode webhook

Review the dry-run before removing --dry-run. Keep the private project’s token in the same protected secret channel. Keep TLS verification enabled; use --ca-bundle-path for a self-managed private CA.

Configure the webhook

You need the Maintainer or Owner role to create a project webhook in GitLab.

Open the project and select Settings → Webhooks → Add new webhook.
Set URL to the full HTTPS address of the CodeGraph API with the path /api/v1/admin/runtime/webhooks/gitlab. For example: https://codegraph.customer.example/api/v1/admin/runtime/webhooks/gitlab. Replace the domain with an address the GitLab server can reach.
Set Secret token to the value configured as GITLAB_WEBHOOK_SECRET in CodeGraph. The CodeGraph receiver checks this token from the X-Gitlab-Token header.
Select push and merge request events.
Keep SSL verification enabled and save the webhook.

GitLab also supports a separate Signing token, which adds an HMAC-SHA256 signature in the webhook-signature header. The current CodeGraph receiver authenticates with the Secret token value in X-Gitlab-Token; it does not validate webhook-signature. Configure Secret token for this endpoint: a signing token alone will not authenticate the delivery. GitLab recommends signing tokens for new webhooks; see its current webhook guidance for the available fields.

POST /api/v1/admin/runtime/webhooks/gitlab

Set the same value as GITLAB_WEBHOOK_SECRET in CodeGraph. GitLab sends the event type in X-Gitlab-Event and the shared token as a plain header value in X-Gitlab-Token; CodeGraph compares the token in constant time. Use HTTPS, keep SSL verification enabled, restrict ingress to the webhook route, redact the token from logs, and rotate it through your deployment’s secret management.

What happens after delivery

For a Push Hook, CodeGraph converts project.path_with_namespace, project.git_http_url, ref, before, after, and changed paths in commits into a shared push event. The sync queue resolves the repository binding and selects an enabled canonical tracked branch. With no explicit tracked branches, the default branch acts as the canonical branch. The queue saves the event and creates a sync job; the same binding, branch ref, and after commit identify a repeated push.

For a Merge Request Hook, CodeGraph reads object_attributes: the request number, action, source and target branches, and commit IDs. The review queue uses this state to create a review snapshot and its processing job.

The HTTP 202 response contains status, event_type, job_id, and detail:

What happens after delivery
Field	Meaning
`job_id`	The associated sync or review 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`	Merge-request identity, normalized action, and saved review snapshot ID.
`detail.reason`	Why the event was skipped, such as `unsupported_event_type`, `repository_not_bound`, `binding_inactive`, or `branch_not_tracked`.

For example, a Push Hook for refs/heads/main that changes src/auth.py returns the new commit in detail.commit and detail.changed_files: 1. Follow job_id to the final sync result, then compare the repository HEAD and CPG HEAD. For a merge request, retain detail.snapshot_id to reopen the saved review. Use status and detail.reason to identify a skipped event and correct its repository binding, branch tracking, or event subscription before sending it again.

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.

Where to check the result
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

Bindings, sync jobs, backlogs, review snapshots, and recovery actions are exposed below:

/api/v1/integrations/repositories
POST /api/v1/integrations/repositories/review-snapshots/{snapshot_id}/rerun
GET /api/v1/admin/runtime/webhooks/status/{project_id}

A rerun posts a GitLab note only when publish_review is requested and a provider token is available. Confirm the stored publication status and the note on the merge request.

The equivalent operator commands are under python -m src.cli repos. Check provider-health first, then the exact binding and failed job. Replay only a failed job and verify repository HEAD against CPG HEAD; use the job and repository status to confirm completion.

Security boundary

Scope the access token to the repositories and API operations required by the pilot.
Restrict the admin runtime webhook route and redact X-Gitlab-Token from logs.
Do not disable TLS for a self-managed server; install the issuing CA instead.
Treat merge-request titles, diffs, and comments as untrusted data before LLM processing.

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.