Webhook и автоматический review
Подробно о webhook в Istok Connect: какие провайдеры поддержаны, что запускается по push и PR или MR, почему localhost не подходит и где искать причину сбоя.
- Нужно включить автоматический review без ручной вставки diff
- Webhook включается с ошибкой или не даёт ожидаемого результата
- Нужно объяснить команде, что именно будет происходить автоматически
- Понимание, какие провайдеры и способы подключения реально поддержаны
- Чёткое представление о том, какие события запускают синхронизацию, а какие review
- Рабочий список причин, почему webhook может не сработать
Что именно делает webhook
В практическом сценарии пользователь ставит webhook Istok Connect в свой GitHub или GitLab репозиторий. После этого Git-провайдер начинает отправлять события в backend Istok Connect, а backend уже решает, что именно делать дальше: синхронизировать репозиторий или запускать review изменений.
Webhook в Istok Connect закрывает две разные задачи. Push-событие запускает фоновую синхронизацию репозитория. Событие PR или MR запускает автоматический review изменений.
Это важно не смешивать. Если после push вы ждёте карточку review, это не признак поломки. Встроенная логика специально отделяет обновление индекса от анализа изменений в pull request и merge request.
Какие сценарии поддержаны сейчас
Поддержка webhook и автоматического review зависит не только от того, что репозиторий уже подключён, но и от конкретного типа интеграции. Поэтому одинаковое ожидание для всех провайдеров здесь приводит к ложным выводам о поломке.
- GitHub и GitLab можно включить из интерфейса. Для них создаётся webhook на стороне провайдера и сохраняется секрет проверки.
- GitHub App репозитории используют webhook на уровне приложения. Для них нужен webhook в настройках GitHub App, а не обычная кнопка на карточке репозитория.
- Gitea и GitFlic можно подключать для индексации и ручного review по diff, но встроенная авто-регистрация webhook в текущей версии для них недоступна.
Рабочий порядок настройки
Ниже не абстрактная рекомендация, а реальный пользовательский сценарий продукта. Вы подключаете репозиторий в Connect, и в этот же момент Connect автоматически регистрирует webhook у провайдера, если у токена есть нужные права. Если авто-регистрация не прошла, например из-за нехватки прав, webhook можно включить вручную на карточке репозитория. Дальше события приходят в backend Connect и превращаются в sync или review.
Подключите репозиторий
Для GitHub и GitLab webhook регистрируется автоматически сразу после подключения. Если для этого не хватило прав у токена, в карточке появится кнопка включения webhook.
Проверьте статус webhook
На карточке репозитория отображается статус webhook. Если он не зарегистрирован, нажмите кнопку включения — Connect повторит регистрацию.
Для GitHub App — отдельный app-level webhook
Репозитории через GitHub App используют общий app-level webhook, а не обычный webhook карточки. Его настройка — в конфигурации GitHub App на стороне админа платформы.
Создайте или обновите PR либо MR
Review стартует на событиях создания и обновления, а не просто на push в ветку.
Проверьте историю review
Результат нужно искать внутри проекта Connect, где хранится история анализов.
Нужно ли собирать webhook URL вручную
Нет. В обычном пользовательском сценарии собирать webhook URL руками не нужно. Для GitHub и GitLab Connect регистрирует webhook автоматически сразу после подключения репозитория. Если прав у токена не хватило, на карточке появляется кнопка включения webhook — она повторяет регистрацию.
Если вы пытаетесь собрать URL сами по шаблону, это почти наверняка будет ошибкой. У каждого подключённого репозитория свой внутренний идентификатор, поэтому корректный callback создаётся только после того, как репозиторий уже подключён в Connect. В пользовательской инструкции важен не внутренний маршрут backend, а факт, что URL и секрет выдаёт сам Connect.
- GitHub: endpoint у провайдера создаётся с событиями push и pull_request.
- GitLab: endpoint у провайдера создаётся с push_events и merge_requests_events.
- Для GitHub запросы проверяются по заголовку X-Hub-Signature-256.
- Для GitLab запросы проверяются по заголовку X-Gitlab-Token.
Где это настраивается у провайдера
Для GitHub ручная настройка физически находится в Settings репозитория, затем Webhooks, затем Add webhook. Но в текущем продукте обычному пользователю не нужно вручную заполнять Payload URL и secret, потому что это делает Connect по кнопке включения.
Для GitLab ручная настройка физически находится в Settings проекта, затем Webhooks. Но и здесь рабочий пользовательский сценарий тот же самый: сначала подключить репозиторий в Connect, потом включить webhook в Connect, а не собирать callback руками.
Требования к контуру и проверка подлинности
Webhook требует публичный URL, доступный GitHub или GitLab. На localhost провайдер не сможет доставить событие до вашего окружения. Для локальной разработки используйте туннель или ручной review по diff.
GitHub запросы проверяются по подписи X-Hub-Signature-256. GitLab запросы проверяются по X-Gitlab-Token. Если секрет не совпал или webhook не был зарегистрирован для этого репозитория, событие будет отклонено.
Что важно понимать про GitHub App
GitHub App не использует обычный сценарий "добавить webhook на карточке одного репозитория". В коде продукта этот случай отделён отдельно и считается app-level сценарием. Поэтому обычная инструкция для GitHub репозитория без GitHub App сюда не переносится автоматически.
Именно поэтому в текущем интерфейсе нет честного места, где можно просто взять готовый URL для GitHub App репозитория так же, как для обычного GitHub webhook. Для такого сценария нужно настраивать webhook на уровне GitHub App settings и сверять это уже с вашим контуром внедрения, а не с карточкой одного подключённого репозитория.
Самые частые причины, почему ничего не произошло
Если webhook включён, но вы не видите ожидаемого эффекта, причина обычно не одна большая поломка, а несовпадение сценария с тем, как продукт реально работает. Этот список стоит проверять сверху вниз.
- Репозиторий подключён через GitHub App, а вы пытаетесь включить обычный webhook на уровне одного репозитория.
- Провайдер Gitea или GitFlic подключён успешно, но вы ждёте сценарий авто-регистрации webhook, которого сейчас нет.
- Событие было обычным push в ветку. В этом случае пойдёт синхронизация, а не review.
- Стенд доступен только локально или за закрытым адресом, до которого провайдер не может достучаться.
- Вы ищете результат в GitHub или GitLab, хотя карточка review публикуется в истории Connect внутри проекта.