Deploy Hooks

Deploy Hooks — это специальные URL, которые позволяют триггерить деплои из внешних систем без настройки Git webhooks.

Когда использовать

• CI/CD пайплайны — деплой после успешных тестов
• CMS — деплой при обновлении контента
• Scheduled deployments — деплой по расписанию (cron)
• Manual triggers — кнопка деплоя в других системах

Совет

Deploy Hooks не требуют изменений в репозитории. Полезно когда нужен деплой без нового коммита.

Создание Deploy Hook

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

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

2. Найдите секцию Deploy Hooks

3. Нажмите “Create Hook”

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

   Поле	Описание
   Name	Название (для идентификации)
   Branch	Ветка для деплоя
   Scope	Production, Preview, или All

5. Сохраните

   ONREZA сгенерирует уникальный URL и токен

Формат URL

https://api.onreza.ru/v1/hooks/{token}

Где {token} — 64-символьная hex-строка (256 бит энтропии).

Осторожно

URL содержит секретный токен. Не публикуйте его в открытых репозиториях и не логируйте.

Использование

curl

curl -X POST https://api.onreza.ru/v1/hooks/{token} \
  -H "Content-Type: application/json" \
  -d '{
    "commitSha": "abc123def456...",
    "branch": "main",
    "message": "Deploy from CI"
  }'

GitHub Actions

name: Deploy to ONREZA

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Trigger Deploy Hook
        run: |
          curl -X POST "${{ secrets.ONREZA_DEPLOY_HOOK_URL }}" \
            -H "Content-Type: application/json" \
            -d "{\"commitSha\": \"${{ github.sha }}\", \"branch\": \"${{ github.ref_name }}\", \"message\": \"Deploy from GitHub Actions\"}"

GitLab CI

deploy:
  stage: deploy
  script:
    - |
      curl -X POST "$ONREZA_DEPLOY_HOOK_URL" \
        -H "Content-Type: application/json" \
        -d "{\"commitSha\": \"$CI_COMMIT_SHA\", \"branch\": \"$CI_COMMIT_BRANCH\", \"message\": \"Deploy from GitLab CI\"}"
  only:
    - main

Scheduled (cron)

# crontab -e
# Деплой каждый день в 3:00
0 3 * * * curl -X POST "https://api.onreza.ru/v1/hooks/YOUR_TOKEN" -H "Content-Type: application/json" -d '{"commitSha":"latest","branch":"main","message":"Scheduled deploy"}'

Заголовок X-Workspace

Заметка

Заголовок X-Workspace указывает slug рабочего пространства. При использовании CLI или API key с префиксом nrz_ заголовок не требуется.

Способ аутентификации	Требуется X-Workspace
Session (cookie)	Да
API ключ (nrz_*)	Нет (workspace в токене)
Device Flow	Нет (workspace в токене)

Scope (Область)

Scope	Описание
Production	Создаёт production deployment
Preview	Создаёт preview deployment
All	Создаёт деплой согласно branch pattern

Параметры запроса

Параметр	Обязательный	Описание
commitSha	Да	SHA коммита для деплоя (40 символов hex)
branch	Да	Ветка для деплоя
message	Да	Сообщение деплоя (до 500 символов)
author	Нет	Автор деплоя (до 200 символов)

Ответ API

При успешном триггере возвращается:

{
  "id": "deployment-uuid",
  "status": "PENDING",
  "isPreview": false,
  "url": "https://myproject-abc123-workspace.onreza.app",
  "urls": {
    "unique": "https://myproject-abc123-workspace.onreza.app",
    "branch": "https://myproject-git-main-workspace.onreza.app",
    "production": "https://myproject-workspace.onreza.app"
  },
  "message": "Deployment triggered successfully via webhook"
}

Управление Deploy Hooks

Просмотр статистики

На странице Deploy Hooks видна статистика:

• Triggered Count — сколько раз использовался
• Last Triggered — когда последний раз

Регенерация токена

Если токен скомпрометирован:

1. Найдите hook в списке
2. Нажмите Regenerate
3. Скопируйте новый URL
4. Обновите URL во всех системах

Осторожно

Старый токен перестаёт работать сразу после регенерации.

Удаление

1. Найдите hook в списке
2. Нажмите удалить (корзина)
3. Подтвердите

Отличие от Webhooks

Характеристика	Webhooks	Deploy Hooks
Источник	Git провайдер	Любая система
Триггер	git push	HTTP POST или CLI
Автоматически	Да	Нужен явный вызов
Commit info	Из git	Указывается вручную

Security

Защита URL

• Храните URL в секретах (GitHub Secrets, GitLab Variables)
• Не логируйте URL
• Регулярно ротируйте токены

Rate Limiting

Заметка

Сейчас Deploy Hooks не имеют rate limiting. Не злоупотребляйте API — избыточные запросы могут привести к блокировке.

Troubleshooting

”Invalid token”

1. Проверьте что URL скопирован полностью
2. Проверьте что hook не был удалён
3. Регенерируйте токен если нужно

”X-Workspace header is required”

1. Используйте CLI вместо прямых HTTP-запросов
2. Или убедитесь что используете API key аутентификацию

Scope не соответствует ветке

Ошибка: Hook is scoped to PRODUCTION, but branch 'feature' is not production branch

1. Проверьте scope hook’а
2. Используйте scope All если хотите деплоить любую ветку
3. Или создайте отдельные hooks для production и preview

Деплой не создаётся

1. Проверьте scope — возможно он не соответствует ветке
2. Проверьте что ветка существует в репозитории
3. Проверьте логи в ONREZA

”Branch not found”

1. Убедитесь что ветка существует в репозитории
2. Проверьте что Git провайдер подключён
3. Проверьте что токен провайдера действителен

Use Cases

Deploy после тестов

# GitHub Actions
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

  deploy:
    needs: test  # Только после успешных тестов
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Trigger Deploy Hook
        run: |
          curl -X POST "${{ secrets.ONREZA_DEPLOY_HOOK_URL }}" \
            -H "Content-Type: application/json" \
            -d "{\"commitSha\": \"${{ github.sha }}\", \"branch\": \"main\", \"message\": \"Deploy after tests\"}"

Deploy при обновлении CMS

// Headless CMS webhook handler
export async function handleContentUpdate(event) {
  // Триггер деплоя при публикации контента
  await fetch(process.env.ONREZA_DEPLOY_HOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      commitSha: 'latest',
      branch: 'main',
      message: `CMS update: ${event.type}`,
    }),
  });
}

Scheduled rebuild для static sites

# Ежедневный rebuild в 3:00 для обновления данных
0 3 * * * curl -X POST "https://api.onreza.ru/v1/hooks/YOUR_TOKEN" -H "Content-Type: application/json" -d '{"commitSha":"latest","branch":"main","message":"Scheduled rebuild"}'

См. также

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