Интеграция с GitVerse — Документация CodeGraph

Интеграция с GitVerse поддерживает подключение репозиториев, синхронизацию по запросу оператора, согласование вебхука, запуск workflow и операции ревью pull request. Здесь описаны операции провайдера, а общий процесс — в Импорте проекта.

Возможности интеграции

Возможности интеграции
Возможность	Текущая поддержка
Метаданные репозитория через API провайдера	Да
Получение HEAD ветки	Да
Список репозиториев пространства имён	Да
Синхронизация проекта по запросу оператора	Доступна
Операция согласования вебхука	Доступна
Ревью и повторная публикация для pull request	Доступны

В разделе «Операции GitVerse» приведены запросы для синхронизации проекта, запуска workflow, ревью pull request и повторной публикации ревью.

Подключение и импорт

Выполняйте команды в PowerShell из корня исходного репозитория CodeGraph. Нужны установленное Python-окружение проекта и настроенный сервер. Выберите существующую группу доступа: подключение и импорт будут сохранены в ней. Замените OWNER/REPOSITORY своим значением. Импорт создаёт или находит проект для репозитория и выводит его имя.

Примеры используют группу default. Для другой группы добавьте --group "<имя-группы>" во все команды. По умолчанию импорт использует ручную синхронизацию. Чтобы запустить обновление после импорта, используйте операцию sync-now ниже.

python -m src.cli repos connect-provider --name gitverse-main --provider gitverse --base-url https://api.gitverse.ru --host gitverse.ru
python -m src.cli repos provider-health --connection gitverse-main
python -m src.cli repos import --connection gitverse-main --repo 'OWNER/REPOSITORY'
python -m src.cli repos status

После создания подключения CLI выводит Created provider connection: gitverse-main. При успешном импорте найдите строки Imported repository … into project …, Binding id:, Mirror: и Heads: repo=… cpg=…. Сохраните идентификатор привязки, чтобы проверять синхронизацию.

Для приватного репозитория передайте токен через --token команды connect-provider, используя значение из защищённого канала секретов вашей организации. Не сохраняйте его в конфигурации под Git. Проверку TLS оставьте включённой; --ca-bundle-path нужен только для частного центра сертификации.

Ручная синхронизация и состояние вебхука

Чтобы обновить GitVerse-проект после импорта, вызовите:

POST /api/v1/integrations/repositories/gitverse/projects/{project_name}/sync-now

Ответ содержит status=accepted, correlation_id и next_poll_url. Откройте next_poll_url, чтобы проверить операцию в сводке GitVerse.

Приёмник по адресу POST /api/v1/webhooks/gitverse ожидает X-GitVerse-Signature и проверяет его по значению GITVERSE_WEBHOOK_SECRET. В руководстве GitVerse по вебхукам и API создания вебхука описан заголовок Authorization, но не формат совместимой подписи. Для подтверждённого обновления используйте sync-now. Операция reconcile-webhook приводит существующий вебхук к адресу CodeGraph; ответ о принятии запускает согласование, но не проверяет доставку события.

Где проверить результат

Отправляйте запросы с авторизацией по справочнику REST API. Для операций GitVerse передавайте токен провайдера в X-GitVerse-Token или настройте GITVERSE_TOKEN на сервере. Получите binding_id из GET /api/v1/integrations/repositories/bindings и подставляйте его в маршруты привязки.

Где проверить результат
Что проверить	Запрос и результат
Состояние синхронизации	Перейдите по `next_poll_url` из ответа `sync-now`; сопоставьте операцию по `correlation_id`.
Задание синхронизации	`GET /api/v1/integrations/repositories/bindings/{binding_id}/sync-jobs`: проверьте `status`, `commit_sha`, `result` и `error` для ожидаемой ревизии репозитория.
Текущая ревизия графа	`GET /api/v1/integrations/repositories/bindings/{binding_id}`: сравните `repository_head_sha` и `cpg_head_sha` после завершения задания.
Ревью pull request	Перейдите по `next_poll_url` из ответа операции ревью, затем проверьте результат и публикацию в целевом pull request.

В списках заданий проверяйте has_next. Чтобы перейти к следующей странице, увеличьте offset на возвращённый limit и повторите запрос. Сопоставляйте идентификатор задания, а не только первую запись списка.

Операции GitVerse

Общие привязки и задания находятся под путём:

/api/v1/integrations/repositories
POST /api/v1/integrations/repositories/review-snapshots/{snapshot_id}/rerun

Общий повтор публикует комментарий, только если запрошен publish_review. Провайдерные маршруты ниже позволяют оператору управлять GitVerse и повторно публиковать ревью.

GitVerse добавляет актуальное семейство маршрутов:

GET  /api/v1/integrations/repositories/gitverse/overview
POST /api/v1/integrations/repositories/gitverse/projects/{project_name}/validate
POST /api/v1/integrations/repositories/gitverse/projects/{project_name}/reconcile-webhook
POST /api/v1/integrations/repositories/gitverse/projects/{project_name}/sync-now
POST /api/v1/integrations/repositories/gitverse/projects/{project_name}/dispatch-workflow
POST /api/v1/integrations/repositories/gitverse/projects/{project_name}/pull-requests/{pr_number}/review
POST /api/v1/integrations/repositories/gitverse/projects/{project_name}/pull-requests/{pr_number}/republish
DELETE /api/v1/integrations/repositories/gitverse/projects/{project_name}/binding

Публикация ревью — отдельное действие со своим статусом. Перейдите по next_poll_url из ответа операции, затем проверьте результат в целевом pull request.

Восстановление и откат

Начните с provider-health, затем проверьте проект. Используйте sync-now для обновления по запросу оператора. Перед повтором изучите неуспешную операцию или задание в repository suite. Удалите привязку GitVerse запросом DELETE /api/v1/integrations/repositories/gitverse/projects/{project_name}/binding.

Граница безопасности

Ограничьте права токена и ротируйте его отдельно от секрета вебхука.
Разрешайте validate, sync, dispatch, retry, review и republish только операторам.
Не пишите подписи в логи и не отключайте проверку TLS.
Считайте payload pull request и ответы провайдера недоверенными данными.

Справка и диагностика

Параметры подключения и импорта: руководство CLI.
Авторизация, привязки и задания ревью: REST API.
Подготовка проекта и проверка результата импорта: импорт проекта.