Руководство подходит для GitLab.com и собственного экземпляра GitLab. CodeGraph получает метаданные репозитория, импортирует проекты группы, синхронизирует push-события и создаёт снимки ревью для merge request. Общий процесс описан в Импорте проекта.
Возможности интеграции
| Возможность | Текущая поддержка |
|---|---|
| Метаданные репозитория через GitLab API v4 | Да |
| Получение HEAD ветки | Да |
| Список репозиториев группы | Да |
| Входящий вебхук push и merge request | Да |
| Публикация комментария ревью | Да, через задание снимка ревью с публикацией в merge request |
Подключение и импорт
Выполняйте команды в PowerShell из корня исходного репозитория CodeGraph. Нужны установленное
Python-окружение проекта и настроенный сервер. Выберите существующую группу доступа:
подключение и импорт будут сохранены в ней. Замените GROUP/REPOSITORY и GROUP своими
значениями. Импорт создаёт или находит проект для репозитория и выводит его имя.
В --base-url укажите корень API, а в --host — адрес для клонирования:
Примеры используют группу default. Для другой группы добавьте --group "<имя-группы>"
во все команды. Параметр --sync-mode webhook выбирает синхронизацию по событиям
репозитория; без него импорт использует режим manual.
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
После создания подключения CLI выводит Created provider connection: gitlab-main.
При успешном импорте найдите строки Imported repository … into project …, Binding id:,
Mirror: и Heads: repo=… cpg=…. Сохраните идентификатор привязки для проверки заданий вебхука.
Для приватного проекта нужен токен провайдера. CLI принимает его через --token, но буквальное
значение может остаться в истории команд или быть видно при просмотре процессов. Передавайте токен
только через защищённый канал секретов вашей инфраструктуры, затем проверьте provider-health.
Для ограниченного импорта группы используйте то же подключение:
python -m src.cli repos bulk-import --connection gitlab-main --namespace 'GROUP' --dry-run --sync-mode webhook
Сначала проверьте план, затем при необходимости уберите --dry-run. Токен приватного проекта храните
в том же защищённом канале секретов. Проверку TLS не отключайте; для собственного центра сертификации
используйте --ca-bundle-path.
Настройка вебхука
Для создания вебхука проекта нужна роль Maintainer или Owner в GitLab.
- Откройте проект и выберите
Settings → Webhooks → Add new webhook. - В поле
URLукажите полный HTTPS-адрес API CodeGraph с путём/api/v1/admin/runtime/webhooks/gitlab. Например:https://codegraph.customer.example/api/v1/admin/runtime/webhooks/gitlab. Замените домен адресом, доступным серверу GitLab. - В поле
Secret tokenзадайте значение, совпадающее сGITLAB_WEBHOOK_SECRETв CodeGraph. Приёмник CodeGraph проверяет этот токен из заголовкаX-Gitlab-Token. - Выберите события push и merge request.
- Оставьте проверку SSL включённой и сохраните вебхук.
GitLab также поддерживает отдельный Signing token: он добавляет подпись HMAC-SHA256 в заголовок webhook-signature. Текущий приёмник CodeGraph аутентифицирует запрос по значению Secret token из заголовка X-Gitlab-Token; подпись webhook-signature он не проверяет. Для этого маршрута заполните Secret token: одного Signing token недостаточно. GitLab рекомендует Signing token для новых вебхуков; доступные поля описаны в актуальной документации GitLab.
POST /api/v1/admin/runtime/webhooks/gitlab
То же значение задайте в CodeGraph как GITLAB_WEBHOOK_SECRET. GitLab передаёт тип события в
X-Gitlab-Event, а общий токен — открытым значением заголовка X-Gitlab-Token; CodeGraph сравнивает
токен за постоянное время. Используйте HTTPS и оставьте проверку SSL включённой. Ограничьте входящие запросы маршрутом
вебхука, удаляйте токен из журналов и храните его в системе управления секретами.
Что происходит после доставки
Для Push Hook CodeGraph преобразует project.path_with_namespace,
project.git_http_url, ref, before, after и изменённые пути из commits
в общее push-событие. Очередь синхронизации находит привязку репозитория и выбирает
включённую каноническую отслеживаемую ветку. Если явно заданных отслеживаемых веток
нет, канонической служит ветка по умолчанию. Очередь сохраняет событие и создаёт
задание. Повторный push определяется по той же привязке, ref и коммиту after.
Для Merge Request Hook CodeGraph читает object_attributes: номер запроса,
действие, исходную и целевую ветки и коммиты. Очередь ревью использует это состояние
для создания снимка и задания его обработки.
Ответ HTTP 202 содержит status, event_type, job_id и detail:
| Поле | Значение |
|---|---|
job_id |
Идентификатор связанного задания синхронизации или ревью, если оно есть. |
detail.commit / detail.changed_files |
Коммит after и число изменённых путей push-события. |
detail.ingest_status |
Результат очереди синхронизации, например accepted или deduplicated. |
detail.review_id / detail.action / detail.snapshot_id |
Номер merge request, нормализованное действие и идентификатор снимка ревью. |
detail.reason |
Причина пропуска: например, unsupported_event_type, repository_not_bound, binding_inactive или branch_not_tracked. |
Например, Push Hook для refs/heads/main, меняющий src/auth.py, передаёт новый
коммит в detail.commit и возвращает detail.changed_files: 1. По job_id найдите
итоговый результат синхронизации, затем сравните HEAD репозитория и CPG. Для merge
request сохраните detail.snapshot_id, чтобы вернуться к записанному ревью.
По status и detail.reason определите причину пропуска и перед повторной отправкой
исправьте привязку репозитория, отслеживание ветки или подписку на события.
Где проверить результат
Отправляйте запросы с авторизацией по справочнику REST API. Получите binding_id из списка доступных привязок репозиториев: GET /api/v1/integrations/repositories/bindings. Подставьте этот идентификатор в маршруты ниже. Для ревью используйте detail.snapshot_id из ответа вебхука.
| Что проверить | Запрос и результат |
|---|---|
| Синхронизация после push | GET /api/v1/integrations/repositories/bindings/{binding_id}/sync-jobs: найдите в items запись с id, равным job_id из ответа вебхука; проверьте status, commit_sha, result и error. |
| Текущая ревизия графа | GET /api/v1/integrations/repositories/bindings/{binding_id}: сравните repository_head_sha и cpg_head_sha после завершения задания. |
| Обработка PR/MR | GET /api/v1/integrations/repositories/review-snapshots/{snapshot_id}/jobs: проверьте задания сохранённого снимка ревью. |
В списках заданий проверяйте has_next. Чтобы перейти к следующей странице, увеличьте offset на возвращённый limit и повторите запрос. Сопоставляйте идентификатор задания, а не только первую запись списка.
Наблюдение и восстановление
Привязки, задания синхронизации, очередь, снимки ревью и восстановление доступны по путям:
/api/v1/integrations/repositories
POST /api/v1/integrations/repositories/review-snapshots/{snapshot_id}/rerun
GET /api/v1/admin/runtime/webhooks/status/{project_id}
Повторное задание публикует заметку GitLab, если запрошен publish_review и доступен токен
провайдера. Проверьте записанный статус публикации и саму заметку в merge request.
Аналогичные команды находятся под python -m src.cli repos. Сначала проверьте
provider-health, затем конкретную привязку и неуспешное задание. Повторяйте только это задание и
сверяйте HEAD репозитория с HEAD CPG: завершение подтверждается статусом задания и репозитория.
Граница безопасности
- Ограничьте токен репозиториями и API-операциями пилота.
- Закройте административный runtime-маршрут от обычных пользователей и удаляйте
X-Gitlab-Tokenиз логов. - Для собственного сервера установите доверенный CA вместо отключения TLS.
- Считайте заголовки, diff и комментарии merge request недоверенными данными до LLM-обработки.
Справка и диагностика
Параметры команд репозиториев описаны в руководстве CLI, а доступные операции сервера — в справочнике REST API. Если подключение или задание завершилось ошибкой, используйте руководство по диагностике.