Настройка Webhooks

Webhooks позволяют автоматически запускать деплой при каждом пуше в ваш Git репозиторий. Когда вы делаете git push, Git провайдер отправляет уведомление в ONREZA, и платформа автоматически создаёт новый деплой.

Как это работает

1. Вы настраиваете webhook в вашем Git провайдере (GitVerse или SourceCraft)
2. При каждом пуше провайдер отправляет HTTP-запрос на ONREZA
3. ONREZA проверяет подлинность запроса по секретному ключу
4. Если проверка успешна — создаётся новый деплой

Совет

Каждый проект в ONREZA имеет уникальный секрет. Это позволяет иметь несколько проектов из одного репозитория — каждый со своим webhook.

Предварительные требования

• Проект создан в ONREZA и подключён к Git репозиторию
• Доступ к настройкам репозитория в GitVerse или SourceCraft
• Права на создание webhooks в репозитории

Настройка в ONREZA

1. Откройте настройки проекта

   Перейдите в ваш проект → Settings → Git

   

2. Включите автоматический деплой

   В секции Incoming Webhooks включите переключатель Автоматический деплой

3. Сгенерируйте секрет

   Нажмите Сгенерировать секрет. Этот секрет нужен для проверки подлинности запросов от Git провайдера.

4. Скопируйте данные

   Вам понадобятся:

   • Webhook URL — адрес для отправки уведомлений
   • Webhook Secret — секретный ключ для авторизации

Настройка в Git провайдере

GitHub

Настройка webhook в GitHub

Для проектов из GitHub репозиториев webhooks настраиваются автоматически при установке GitHub App. Никаких дополнительных действий не требуется.

Совет

GitHub App автоматически создаёт webhook с правильными настройками. При каждом пуше или создании Pull Request, ONREZA получает уведомление и создаёт деплой.

Проверка webhook в GitHub

Если хотите убедиться что webhook настроен:

1. Откройте настройки репозитория

   Перейдите в ваш репозиторий на GitHub → Settings → Webhooks

2. Проверьте наличие webhook

   Вы должны увидеть webhook от “ONREZA GitHub App”

3. Проверьте события

   Webhook настроен на события:

   • Push — для деплоя при пуше коммитов
   • Pull Request — для preview деплоев

Переустановка GitHub App

Если webhook не работает:

1. Откройте Account → Settings → Authentication
2. Найдите GitHub и нажмите Install GitHub App
3. Выберите “Configure” рядом с вашим аккаунтом
4. Убедитесь что репозиторий выбран в списке

GitVerse

Настройка webhook в GitVerse

1. Откройте настройки репозитория

   Перейдите в ваш репозиторий на GitVerse → Settings → Webhooks

2. Создайте новый webhook

   Нажмите Add webhook или Добавить webhook

3. Заполните форму

   Поле	Значение
   URL	Вставьте Webhook URL из ONREZA
   Authorization	Вставьте секрет (только значение, без Bearer)
   Content Type	application/json

   Осторожно

   В поле Authorization вставьте секрет напрямую, без префикса Bearer. Например: abc123secret, а не Bearer abc123secret.

4. Выберите события

   Отметьте события, которые будут триггерить webhook:

   • Push — для деплоя при пуше коммитов
   • Pull Request — для preview деплоев (опционально)

5. Сохраните webhook

   Нажмите Add webhook. GitVerse отправит тестовый запрос для проверки.

SourceCraft

Настройка webhook в SourceCraft

1. Откройте настройки репозитория

   Перейдите в ваш репозиторий на SourceCraft → Settings → Webhooks

2. Создайте новый webhook

   Нажмите Create webhook

3. Заполните форму

   Поле	Значение
   URL	Вставьте Webhook URL из ONREZA
   Secret	Вставьте секрет из ONREZA
   Content Type	application/json

   Заметка

   SourceCraft использует секрет для создания HMAC подписи. Эта подпись передаётся в заголовке x-src-signature и проверяется на стороне ONREZA.

4. Выберите события

   Отметьте событие:

   • repository.push — для деплоя при пуше коммитов

5. Сохраните webhook

   Нажмите Create. SourceCraft создаст webhook.

Проверка работы

После настройки сделайте тестовый пуш в репозиторий:

git commit --allow-empty -m "Test webhook"
git push

Если всё настроено правильно, в ONREZA автоматически создастся новый деплой. Вы увидите его на странице проекта в разделе Deployments.

Retry механизм для Git API

Совет

Начиная с февраля 2026, ONREZA использует retry механизм с экспоненциальным backoff для всех Git API запросов.

При получении webhook от Git провайдера, ONREZA выполняет запросы к Git API для получения информации о коммите. Если Git API временно недоступен:

• Автоматические повторные попытки (до 3 раз)
• Экспоненциальная задержка между попытками (1с → 2с → 4с)
• Jitter для предотвращения thundering herd
• Повторные попытки только для transient ошибок (5xx, 429, таймауты)

Это повышает надёжность деплоя при временных проблемах с Git провайдером.

Несколько проектов из одного репозитория

ONREZA поддерживает создание нескольких проектов из одного Git репозитория. Это полезно когда:

• Вы хотите разные настройки сборки для разных окружений
• В монорепозитории несколько приложений
• Нужны разные environment variables для разных инстансов

Совет

Каждый проект имеет уникальный секрет. При получении webhook ONREZA определяет целевой проект именно по секрету, а не по репозиторию.

Как настроить:

1. Создайте несколько проектов в ONREZA из одного репозитория
2. В каждом проекте сгенерируйте свой секрет
3. В Git провайдере создайте отдельный webhook для каждого проекта

Перегенерация секрета

Если секрет был скомпрометирован или вы хотите его обновить:

1. Откройте настройки проекта → Git → Incoming Webhooks
2. Нажмите кнопку перегенерации (иконка обновления) рядом с секретом
3. Подтвердите действие
4. Обязательно обновите секрет в настройках webhook в Git провайдере

Осторожно

После перегенерации старый секрет перестаёт работать немедленно. Webhooks с устаревшим секретом будут отклонены.

Device Flow для CLI

Совет

CLI использует OAuth 2.0 Device Authorization Grant (RFC 8628) для аутентификации без ввода пароля в терминале.

Для настройки автоматического деплоя через CLI:

# Аутентифицируйтесь через Device Flow
nrz login

# В браузере откроется страница подтверждения
# Введите код устройства (например: BCD3-7X9P)

# После подтверждения CLI получит API ключ (nrz_xxxxxxxxxxxx)
# Ключ сохраняется локально и используется для всех команд

Преимущества Device Flow:

• Безопасная аутентификация без передачи пароля через CLI
• API ключ привязан к workspace
• Автоматическое обновление сессии
• Возможность отзыва ключа через веб-интерфейс

Устранение неполадок

Webhook не срабатывает

1. Проверьте что автодеплой включён — переключатель в настройках Git должен быть активен
2. Проверьте секрет — убедитесь что секрет в Git провайдере точно совпадает с секретом в ONREZA
3. Для GitVerse — секрет должен быть без префикса Bearer
4. Проверьте URL — убедитесь что Webhook URL скопирован полностью

Деплой создаётся для неправильного проекта

Если у вас несколько проектов из одного репозитория и деплой создаётся не для того проекта:

1. Убедитесь что для каждого проекта создан отдельный webhook в Git провайдере
2. Проверьте что секреты не перепутаны между проектами
3. Перегенерируйте секреты и заново настройте webhooks

Ошибка авторизации

• GitVerse: Проверьте что секрет в поле Authorization указан без Bearer
• SourceCraft: Убедитесь что секрет указан в поле Secret, а не в URL

Git API недоступен

Если webhook получен но деплой не создаётся:

1. Проверьте логи деплоя в ONREZA
2. Возможны временные проблемы с Git API — retry механизм попытается повторить запросы автоматически
3. Если проблема persists, проверьте статус Git провайдера

См. также

• Git интеграция — обзор интеграции с Git провайдерами
• Деплои — управление деплоями
• Deploy Hooks — ручной триггер деплоев
• CLI аутентификация — Device Flow для CLI