GitLab integration

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.

Supported contract

These capabilities come from src/project_import/repository_suite/repository_provider_adapters.py, not from GitHub-compatible assumptions.

Connect and import

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

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
python -m src.cli repos status

Use the same connection for a bounded group import:

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

Review the dry-run before removing --dry-run. Private projects require a token supplied through the customer’s protected secret channel. Do not record it in repository files or shell history. Keep TLS verification enabled; use --ca-bundle-path for a self-managed private CA.

Configure the webhook

Configure GitLab to send Push Hook and Merge Request Hook events to:

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

Set the shared value as GITLAB_WEBHOOK_SECRET in CodeGraph. GitLab sends the event type in X-Gitlab-Event and the plain secret token in X-Gitlab-Token; CodeGraph compares that token in constant time.

GitLab’s adapter uses ingress restrictions, TLS, secret rotation, provider delivery IDs, and the durable queue’s deduplication for replay control. A 202 Accepted response confirms intake; use the job status and repository state to confirm completion.

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.

Source of truth

• Provider adapter: src/project_import/repository_suite/repository_provider_adapters.py
• Repository CLI: src/cli/repo_suite/repos_parser.py
• Webhook verification: src/api/auth/machine/webhook_auth.py
• Current routes: REST API