Руководство по интеграции с GitLab CE

Production-руководство по эксплуатации CodeGraph с self-managed GitLab Community Edition в локальном контуре: внутренний DNS, приватный CA, локальные раннеры и отсутствие обязательного выхода в интернет.

Содержание¶

Обзор
Профиль локального контура
Provider connection и trust-store
Webhook-настройка и recovery
CI template для локальных раннеров
REST, CLI и MCP surfaces
Workflow ротации
Устранение неполадок
Артефакты приёмки

Обзор¶

CodeGraph поддерживает GitLab CE через каноническую модель provider connection и repository binding. Production-ready контур для локального deployment теперь покрывает:

host-aware provider connections для self-managed GitLab CE;
metadata для custom CA bundle и authenticated health-check;
webhook ingestion для push и merge request событий с delivery diagnostics;
reconcile и replay workflow для пропущенных событий и degraded sync;
review snapshot для merge request с native publication обратно в GitLab notes;
operator-visible status для webhook freshness, repository head, CPG head и review publication;
локальный .gitlab-ci.yml template для private registry и local runners с артефактами JSON, Markdown и SARIF.

Это руководство специально ориентировано на GitLab CE. Оно не предполагает GitLab.com, GitLab EE-only features или доступ к публичному registry во время runtime.

Профиль локального контура¶

Рекомендуемая топология:

GitLab CE доступен по внутреннему hostname, например gitlab.internal.
CodeGraph API доступен по внутреннему hostname, например codegraph.internal.
Reverse proxy проксирует POST /api/v1/webhooks/gitlab в CodeGraph без переписывания body и без потери X-Gitlab-* заголовков.
GitLab runners тянут предзагруженный образ CodeGraph из внутреннего registry, например registry.internal/platform/codegraph-runner:stable.
Контейнеры CodeGraph доверяют тому же приватному CA bundle, которым подписаны сертификаты GitLab CE и reverse proxy.

Требования к reverse proxy:

сохранять X-Forwarded-Proto, Host и X-Gitlab-* заголовки;
принимать body достаточного размера для merge request payload;
не буферизовать и не переписывать webhook JSON;
пропускать быстрый 202 Accepted, пока тяжелая обработка идет асинхронно в фоне.

Минимальные ожидания к machine credential:

использовать service account или PAT, а не human browser session;
для read-only diagnostics и чтения MR metadata достаточно read_api, где этот scope доступен;
для native публикации комментариев в merge request требуется токен с api scope.

Provider connection и trust-store¶

Создание provider connection для GitLab CE с явным host, API version и custom CA bundle:

codegraph repos connect-provider `
  --group default `
  --name gitlab-ce-local `
  --provider gitlab `
  --host gitlab.internal `
  --base-url https://gitlab.internal `
  --api-version v4 `
  --ca-bundle-path C:\certs\gitlab-root-ca.pem `
  --token $env:GITLAB_TOKEN `
  --webhook-secret $env:GITLAB_WEBHOOK_SECRET

Что сохраняется в connection:

provider_host
base_url
metadata.api_version
metadata.ca_bundle_path
service credential и webhook secret

Сразу после создания connection запустите operator health-check:

codegraph repos provider-health --group default --connection gitlab-ce-local

Health-check проверяет:

достижимость hostname;
TLS trust с учетом настроенного CA bundle;
доступность GitLab API v4 version endpoint;
authenticated /user доступ, если токен задан.

Типовые degraded classifications, которые возвращаются оператору:

dns_error:host_resolution_failed
tls_error:tls_verification_failed
auth_error:auth_rejected
provider_http_error:endpoint_not_found
version_mismatch
provider_outage

Импорт репозитория сохраняет стабильную identity и не требует rebind при rename namespace/path, пока не меняется внешний repository ID:

codegraph repos import `
  --group default `
  --connection gitlab-ce-local `
  --repo platform/api `
  --sync-mode webhook

Webhook-настройка и recovery¶

Webhook endpoint:

POST /api/v1/webhooks/gitlab

Настройка в GitLab project:

Откройте Settings > Webhooks.
Укажите https://codegraph.internal/api/v1/webhooks/gitlab.
Задайте тот же secret token, что и в provider connection.
Включите Push events и Merge request events.
Не отключайте SSL verification. Если trust сломан, обновите CA bundle, а не переводите контур в insecure mode.

Поведение webhook path:

CodeGraph быстро отвечает 202 Accepted и ставит durable sync/review work в очередь.
Push events дедуплицируются по binding и event identity.
Merge request events участвуют в lifecycle и dedupe review snapshots.
Delivery diagnostics сохраняются на уровне repository binding и поднимаются в operator surfaces.

Операционный recovery flow:

codegraph repos status --group default --project api
codegraph repos reconcile --group default --project api
codegraph repos jobs --group default --project api --status failed
codegraph repos replay --job-id <failed-sync-job-uuid>
codegraph repos review-snapshots --group default --project api --status failed

GET /api/v1/webhooks/status/{project_id} теперь возвращает и legacy pipeline status, и GitLab-specific binding diagnostics. project_id может быть именем проекта или UUID проекта.

Пример ответа:

{
  "project_id": "api",
  "last_update": "2026-04-19T12:05:00+00:00",
  "status": "completed",
  "commit_sha": "9f21f4e",
  "duration_ms": 2310,
  "gocpg_status": "completed",
  "chromadb_synced": 3,
  "last_webhook_received_at": "2026-04-19T12:03:10+00:00",
  "last_webhook_delivery_at": "2026-04-19T12:03:10+00:00",
  "last_webhook_delivery_status": "accepted",
  "last_webhook_delivery_reason": "event_accepted",
  "last_webhook_delivery_event_type": "merge_request",
  "last_webhook_delivery_id": "2ea7b29d-d418-4cf9-86d6-1d86f32a4488",
  "last_reconcile_at": "2026-04-19T11:48:02+00:00",
  "webhook_health_status": "healthy",
  "reconcile_health_status": "healthy",
  "repository_head_sha": "9f21f4e",
  "cpg_head_sha": "9f21f4e",
  "last_review_publish_at": "2026-04-19T12:04:13+00:00",
  "last_review_publish_status": "published",
  "last_review_publish_reason": "published",
  "last_review_publish_category": "ok",
  "last_review_publish_error": null,
  "error": null
}

CI template для локальных раннеров¶

Эталонный template:

docs/integrations/examples/gitlab_ce_local_contour.gitlab-ci.yml

Предпосылки template:

CODEGRAPH_RUNNER_IMAGE указывает на образ из внутреннего registry, уже зеркалированный в локальный контур;
CODEGRAPH_TOKEN задан как masked GitLab CI variable;
INTERNAL_CA_BUNDLE_PATH указывает на CA bundle, смонтированный в runner image или shell executor;
merge request и default branch pipelines видят полную git history благодаря GIT_DEPTH: "0".

Template публикует:

codegraph-artifacts/security/findings.json
codegraph-artifacts/security/findings.sarif
codegraph-artifacts/review/review-summary.json
codegraph-artifacts/review/review-summary.md
codegraph-artifacts/artifact-index.json

Эти артефакты дают стабильный production contour для:

machine-readable JSON findings;
SARIF export в downstream security tooling;
Markdown summary, который можно прикладывать к MR или хранить как operator evidence.

Обязательные GitLab CI/CD variables:

Переменная	Назначение
`CODEGRAPH_TOKEN`	Bearer token для вызова CodeGraph API
`CODEGRAPH_API_URL`	Внутренний origin CodeGraph API, например `https://codegraph.internal`
`CODEGRAPH_RUNNER_IMAGE`	Образ из внутреннего registry для локальных раннеров
`INTERNAL_CA_BUNDLE_PATH`	Смонтированный путь до private CA bundle внутри раннера

REST, CLI и MCP surfaces¶

REST surfaces:

POST /api/v1/webhooks/gitlab
GET /api/v1/webhooks/status/{project_id}
POST /api/v1/review/mr
POST /api/v1/security/scan-diff
GET /api/v1/repositories/bindings
POST /api/v1/repositories/provider-connections/{connection_id}/health-check

CLI surfaces:

codegraph repos provider-health --group default --connection gitlab-ce-local
codegraph repos status --group default --project api
codegraph repos reconcile --group default --project api
codegraph repos replay --job-id <sync-job-uuid>
codegraph repos review-rerun --snapshot-id <snapshot-uuid> --publish-review

Актуальные MCP surfaces для GitLab-bound repositories:

codegraph_repository_reconcile
codegraph_repository_status
codegraph_repository_sync_jobs
codegraph_review_snapshots
codegraph_review_snapshot_rerun

Workflow ротации¶

Ротация GitLab service credential без re-import репозитория:

codegraph repos rotate-provider-token `
  --group default `
  --connection gitlab-ce-local `
  --token $env:GITLAB_TOKEN_V2 `
  --webhook-secret $env:GITLAB_WEBHOOK_SECRET_V2

Ротация CA bundle path или API metadata на месте:

codegraph repos update-provider `
  --group default `
  --connection gitlab-ce-local `
  --ca-bundle-path C:\certs\gitlab-root-ca-v2.pem `
  --api-version v4

Рекомендуемая последовательность после rotation:

Обновить token или webhook secret.
Запустить codegraph repos provider-health.
Проверить codegraph repos status на webhook/publication diagnostics.
Если freshness отстает от provider head, запустить codegraph repos reconcile.

Human OAuth остается optional для machine workflows. Поддержка custom server URL для self-managed GitLab уже есть, но webhook, sync, reconcile и MR publication не зависят от браузерного логина.

Устранение неполадок¶

`auth_error:auth_rejected`¶

проверьте, что PAT/service token не просрочен;
проверьте, что у токена есть scope, нужный для текущего workflow;
выполните codegraph repos rotate-provider-token, затем codegraph repos provider-health.

`tls_error:tls_verification_failed`¶

проверьте путь к CA bundle, сохраненный в provider connection;
убедитесь, что runner и CodeGraph контейнеры используют один и тот же обновленный CA bundle;
не переходите в insecure TLS как workaround.

`dns_error:host_resolution_failed`¶

проверьте, что hostname GitLab CE резолвится из runtime CodeGraph и из локальных раннеров;
проверьте internal DNS и upstream mapping на reverse proxy.

`last_webhook_delivery_status=deduplicated`¶

это нормальный healthy-сигнал: delivery identity или review snapshot key уже был обработан;
разбираться нужно только если после этого repository_head_sha и cpg_head_sha расходятся.

`last_review_publish_status=failed`¶

посмотрите last_review_publish_reason, last_review_publish_category и last_review_publish_error;
если credentials недавно ротировались, повторно выполните provider health-check;
перезапустите failed review snapshot через codegraph repos review-rerun --publish-review.

Repository head ушел вперед относительно CPG head¶

выполните codegraph repos status --project <project>;
если webhook delivery stale или skipped, выполните codegraph repos reconcile --project <project>;
проверьте failed sync jobs и replay, если корневая причина уже исправлена.

Артефакты приёмки¶

GitLab CE production-readiness rollout отслеживается через:

docs/development/PRD_GITLAB_CE_PRODUCTION_READINESS.md
docs/development/GITLAB_CE_PRODUCTION_READINESS_ACCEPTANCE_CHECKLIST.md
docs/development/GITLAB_CE_PRODUCTION_READINESS_ACCEPTANCE_REPORT.md