Это руководство нужно, когда CodeGraph импортирует репозитории GitHub, синхронизирует CPG после push-событий и создаёт снимки ревью для pull request. Здесь описана только специфика GitHub; общий жизненный цикл репозитория вынесен в Импорт проекта.
Поддерживаемый контракт
| Возможность | Текущая поддержка |
|---|---|
| Метаданные репозитория через API провайдера | Да |
| Получение HEAD ветки | Да |
| Список репозиториев организации или пользователя | Да |
| Входящий вебхук push и pull request | Да |
| Публикация комментария ревью | Да, через общее задание снимка; отдельной точки GitHub нет |
Источник реализации —
src/project_import/repository_suite/repository_provider_adapters.py. Возможности других
провайдеров нельзя автоматически переносить на GitHub.
Подключение и импорт
Публичный репозиторий можно подключить без секрета в командной строке:
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
python -m src.cli repos status
Для приватного репозитория нужен токен. CLI поддерживает --token, но буквальное значение может
остаться в истории shell или попасть в список процессов. Передавайте его только через защищённый
канал секретов, принятый в инфраструктуре заказчика, а затем проверяйте provider-health.
Проверка TLS включена по умолчанию; для частного центра сертификации есть --ca-bundle-path.
Настройка вебхука
Создайте в 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.
Ответ 202 Accepted означает, что событие принято, дедуплицировано либо пропущено и передано в
фоновую обработку. Сопоставьте выданное задание со статусом репозитория, чтобы подтвердить
обновление CPG и ревью.
Наблюдение и восстановление
Общий REST-контур начинается с пути:
/api/v1/integrations/repositories
POST /api/v1/integrations/repositories/review-snapshots/{snapshot_id}/rerun
Через него или команды python -m src.cli repos ... можно проверить привязки, задания
синхронизации, очередь, снимки ревью, pause/resume и ошибки, допускающие повтор. Авторизованному
оператору также доступен статус runtime:
GET /api/v1/admin/runtime/webhooks/status/{project_id}
Повторное задание публикует комментарий GitHub, если запрошен publish_review и доступен токен
провайдера. Появление комментария в pull request подтверждается записанным статусом публикации.
Безопасное восстановление: проверить провайдера, найти привязку и конкретное задание, повторить
только неуспешное задание и убедиться, что HEAD репозитория совпал с HEAD CPG. Завершение повторного
задания подтверждается финальным статусом после ответа 202.
Граница безопасности
- Не храните токены и секреты вебхуков в репозитории и логах.
- Не отключайте TLS; для корпоративного прокси добавьте доверенный CA bundle.
- Ограничьте административный runtime-маршрут операторами. Подпись вебхука подтверждает событие, но не даёт прав на остальные API.
- Считайте содержимое pull request недоверенным вводом до передачи в LLM-сценарий.
Источник истины
- Адаптер провайдера:
src/project_import/repository_suite/repository_provider_adapters.py - CLI репозиториев:
src/cli/repo_suite/repos_parser.py - Приёмник вебхуков:
src/api/routers/collaboration_suite/webhook.py - Сгенерированные маршруты: REST API