Deploy Hooks

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

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

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

Создание Deploy Hook

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

Перейдите в проект → Settings → Git
Найдите секцию Deploy Hooks
Нажмите “Create Hook”
Заполните форму

Поле Описание

Name Название (для идентификации)

Branch Ветка для деплоя

Scope Production, Preview, или All
Сохраните

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

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

Формат URL

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

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

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

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. SHA нужно подставить реальный — например,
# получить его из Git-провайдера перед вызовом hook.
0 3 * * * curl -X POST "https://api.onreza.ru/v1/hooks/YOUR_TOKEN" -H "Content-Type: application/json" -d '{"commitSha":"a1b2c3d","branch":"main","message":"Scheduled deploy"}'

Аутентификация

CRUD endpoints для управления deploy hooks (/v1/deploy-hooks/...) требуют обычную аутентификацию. Для session-запросов передавайте X-Workspace или ?workspace=; workspace API key уже привязан к workspace.

Scope (Область)

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

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

Параметр	Обязательный	Описание
`commitSha`	Да	SHA коммита для деплоя — короткий (от 7 символов) или полный (40 символов) hex. Для GitHub-проектов короткий SHA должен разрешаться GitHub API в один коммит: ONREZA сохранит полный SHA перед деплоем. Значения вроде `latest` недопустимы — передавайте реальный SHA
`branch`	Да	Ветка для деплоя
`message`	Нет	Сообщение деплоя (до 500 символов)
`author`	Нет	Автор деплоя (до 200 символов)
`force`	Нет	Создать деплой даже если идентичный уже существует (обойти дедупликацию)

Ответ 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 — когда последний раз

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

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

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

Удаление

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

Отличие от Webhooks

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

Security

Защита URL

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

Rate Limiting

Troubleshooting

“Invalid token”

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

“X-Workspace header is required”

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

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

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

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

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

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

“Branch not found”

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

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: event.commitSha, // реальный SHA коммита с контентом
      branch: 'main',
      message: `CMS update: ${event.type}`,
    }),
  });
}

Scheduled rebuild для static sites

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

См. также

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