Это руководство нужно, когда CodeGraph импортирует репозитории GitHub, синхронизирует CPG после push-событий и создаёт снимки ревью для pull request. Здесь описана только специфика GitHub; общий жизненный цикл репозитория вынесен в Импорт проекта.
Возможности интеграции
| Возможность | Текущая поддержка |
|---|---|
| Метаданные репозитория через API провайдера | Да |
| Получение HEAD ветки | Да |
| Список репозиториев организации или пользователя | Да |
| Входящий вебхук push и pull request | Да |
| Публикация комментария ревью | Да, через задание снимка ревью с публикацией в pull request |
Подключение и импорт
Выполняйте примеры в PowerShell из корня исходников CodeGraph с установленными Python-зависимостями
и настроенным доступом к серверу. Замените OWNER/REPOSITORY полным именем репозитория.
Команды создают соединение и запускают импорт в группе default. Для другой группы добавьте
--group "<имя-группы>" во все четыре команды. Параметр --sync-mode webhook выбирает
синхронизацию по событиям репозитория; без него импорт использует режим manual.
Публичный репозиторий можно подключить без секрета в командной строке:
python -m src.cli repos connect-provider --name github-main --provider github --base-url https://api.github.com --host github.com
python -m src.cli repos provider-health --connection github-main
python -m src.cli repos import --connection github-main --repo 'OWNER/REPOSITORY' --sync-mode webhook
python -m src.cli repos status
Для приватного репозитория нужен токен. CLI поддерживает --token, но буквальное значение может
остаться в истории командной оболочки или попасть в список процессов. Передавайте его только через защищённый
канал секретов, принятый в инфраструктуре заказчика, а затем проверяйте provider-health.
Проверка TLS включена по умолчанию; для частного центра сертификации есть --ca-bundle-path.
Настройка вебхука
В настройках репозитория GitHub откройте Settings → Webhooks → Add webhook. В поле Payload URL укажите полный HTTPS-адрес API вашего экземпляра CodeGraph, добавив путь ниже. Например: https://codegraph.customer.example/api/v1/admin/runtime/webhooks/github. Замените домен адресом, который GitHub может вызвать. Выберите Content type: application/json и оставьте проверку SSL включённой. Порядок создания описан в документации GitHub.
POST /api/v1/admin/runtime/webhooks/github
Подпишитесь на push и pull_request. Один и тот же секрет задайте в GitHub и в окружении
CodeGraph как GITHUB_WEBHOOK_SECRET. Тип события приходит в X-GitHub-Event, подпись
HMAC-SHA256 — в X-Hub-Signature-256.
Что происходит после доставки
CodeGraph проверяет подпись и преобразует данные GitHub в общее событие
репозитория. Для push он читает имя и адрес клонирования репозитория,
ref, before, after и изменённые пути из commits. Очередь синхронизации
находит привязку репозитория и выбирает включённую каноническую отслеживаемую ветку.
Если явно заданных отслеживаемых веток нет, канонической служит ветка по умолчанию.
Очередь сохраняет событие и создаёт задание синхронизации. Повторный push
с тем же ref и коммитом after сопоставляется с существующим событием этой
привязки. Событие pull_request обрабатывает очередь снимков ревью: CodeGraph
сохраняет номер запроса, действие, исходную и целевую ветки и их коммиты.
Приёмник отвечает HTTP 202 и возвращает status, event_type, job_id
и detail. Следите за обработкой по следующим полям:
| Поле | Значение |
|---|---|
status |
Результат приёма или пропуска события. |
job_id |
Идентификатор связанного фонового задания, если оно есть. |
detail.commit / detail.changed_files |
Коммит after и число изменённых путей push-события. |
detail.ingest_status |
Результат очереди синхронизации, например accepted или deduplicated. |
detail.review_id / detail.action / detail.snapshot_id |
Номер pull request, нормализованное действие и идентификатор снимка ревью. |
detail.reason |
Причина пропуска: например, repository_not_bound, binding_inactive или branch_not_tracked. |
Например, push в refs/heads/main, меняющий src/auth.py, передаёт новый коммит
в detail.commit и возвращает detail.changed_files: 1. Найдите задание по
job_id, дождитесь синхронизации и сравните HEAD репозитория и CPG. Для pull request
сохраните detail.snapshot_id: по нему можно вернуться к ревью записанных
исходной и целевой ревизий.
Для ping приёмник
возвращает status=accepted и detail.message=pong; для неподдерживаемого события —
status=skipped и detail.reason=unsupported_event_type.
Где проверить результат
Отправляйте запросы с авторизацией по справочнику 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 и повторите запрос. Сопоставляйте идентификатор задания, а не только первую запись списка.
Наблюдение и восстановление
Общий REST-контур начинается с пути:
/api/v1/integrations/repositories
POST /api/v1/integrations/repositories/review-snapshots/{snapshot_id}/rerun
Через него или команды python -m src.cli repos ... можно проверить привязки, задания
синхронизации, очередь, снимки ревью, приостановку и возобновление и ошибки, допускающие повтор. Авторизованному
оператору также доступно состояние сервисов:
GET /api/v1/admin/runtime/webhooks/status/{project_id}
Повторное задание публикует комментарий GitHub, если запрошен publish_review и доступен токен
провайдера. Проверьте записанный статус публикации и сам комментарий в pull request.
Безопасное восстановление: проверить провайдера, найти привязку и конкретное задание, повторить
только неуспешное задание и убедиться, что HEAD репозитория совпал с HEAD CPG. Завершение повторного
задания подтверждается финальным статусом после ответа 202.
Граница безопасности
- Не храните токены и секреты вебхуков в репозитории и логах.
- Не отключайте TLS; для корпоративного прокси добавьте набор доверенных сертификатов CA.
- Ограничьте административный runtime-маршрут операторами. Подпись вебхука подтверждает событие, но не даёт прав на остальные API.
- Считайте содержимое pull request недоверенным вводом до передачи в LLM-сценарий.
Справка и диагностика
Параметры команд репозиториев описаны в руководстве CLI, а доступные операции сервера — в справочнике REST API. Если подключение или задание завершилось ошибкой, используйте руководство по диагностике.