Запуск развертываний через Deploy Hooks

A deploy hook is a secret URL that queues a new deployment when something sends it an HTTP POST. There is no authentication header: the secrecy of the URL is the authentication. Use hooks to let a…

Хук развертывания (deploy hook) - это секретный URL, который инициирует новое развертывание при отправке ему HTTP POST запроса. Аутентификационный заголовок не требуется: секретность URL служит аутентификацией. Используйте хуки, чтобы позволить headless CMS, cron заданию, CI pipeline или любому другому webhook перестроить ваш проект без git push.

Где найти хуки развертывания

Хуки находятся на отдельной вкладке: откройте ваш проект в Orbit и нажмите Hooks (Хуки), расположенные на /orbit/<project-id>/hooks.

Та же панель Deploy hooks (Хуки развертывания) также появляется в середине вкладки Settings (Параметры) проекта, поэтому вы можете управлять ими отсюда.

Deploy hooks panel in Orbit

Создание хука развертывания

Откройте Orbit, затем ваш проект, затем Hooks (Хуки).
Нажмите Add deploy hook (Добавить хук развертывания).
Введите Hook name (Имя хука), которое будет понятно через полгода. Подсказка предлагает формат: "Contentful publish", "Nightly cron".
Выберите Target environment (Целевую среду). По умолчанию установлено Production (default) (Производство - по умолчанию). Если у вашего проекта есть staging среда, вы можете указать хук на staging вместо этого.
Нажмите Create hook (Создать хук).

Хук появляется в списке с его URL, кнопкой Copy URL (Копировать URL) и кнопкой Delete hook (Удалить хук).

URL хука

URLs хуков выглядят так:

https://kpanel.kapsulehost.com/api/orbit/hooks/<token>

Токен - это уникальный секрет, сгенерированный при создании хука.

Обращайтесь с URL хука точно как с ключом API. Любой, у кого он есть, может инициировать развертывание вашего проекта, и ни одни из защитных механизмов Orbit его не остановят: блокировки развертывания, требуемое одобрение, обязательные проверки CI и требуемый успех staging применяются только к развертываниям, инициированным push'ем, а хук проходит напрямую. Никогда не вставляйте URL хука в публичный репозиторий, общий документ, скриншот или тикет поддержки.

Инициирование хука

Отправьте POST запрос. Тело и заголовки не требуются.

curl -X POST \
  https://kpanel.kapsulehost.com/api/orbit/hooks/<your-token>

Orbit отвечает с HTTP 202 и ID развертывания. Развертывание появляется на вкладке Deployments (Развертывания) в течение нескольких секунд.

Endpoint принимает только POST. GET запрос не инициирует развертывание. Некоторые старые интеграции webhook по умолчанию используют GET, поэтому проверьте метод, если настроенный вами хук никогда не срабатывает.

Что на самом деле развертывает хук

Хук разрешает свою целевую среду (выбранную вами или production среду проекта), читает ветку этой среды и запрашивает у вашего поставщика git текущий head commit этой ветки. Затем он инициирует развертывание этого commit'а.

Это имеет три важных следствия:

Хук всегда развертывает head ветки. Вы не можете передать SHA commit'а или имя ветки в теле запроса; тело запроса полностью игнорируется.
Хук требует работающего подключения поставщика. Если вы отключили GitHub, GitLab или Bitbucket, хук не может прочитать head ветки и не срабатывает с ошибкой вместо развертывания устаревшего кода.
Хук повторно запускает полную сборку. Это не откат и не promotion; это свежая сборка того, что находится на ветке в данный момент.

Повторные и перекрывающиеся вызовы

Orbit разумно обрабатывает всплески вызовов хуков вместо того, чтобы ставить в очередь сборку для каждого из них.

Если развертывание для того же commit'а уже выполняется на этой среде, хук возвращает существующее развертывание и отмечает ответ как дедублицированный. Вторая сборка не начинается.
Если сборка запущена для другого commit'а на этой среде, она автоматически отменяется и заменяется новой, поэтому вы не платите за сборку, результаты которой уже устарели.

Это делает хуки безопасными для CMS, который отправляет webhook для каждой опубликованной записи. Публикация шести страниц в минуту дает одну сборку, а не шесть, и не сжигает шесть минут сборок.

Подключение headless CMS

Большинство headless CMS имеют функцию "webhook при публикации". Паттерн всегда один и тот же: укажите webhook на ваш URL хука Orbit, используйте POST и оставьте параметры аутентификации пустыми.

Contentful

Перейдите в Settings (Параметры), затем Webhooks (Вебхуки), затем Add webhook (Добавить вебхук).
Установите URL на ваш URL хука Orbit.
Установите метод на POST.
Установите триггер на Publish (Опубликовать) или на те события содержимого, которые должны пересстроить сайт.
Сохраните.

Sanity

В панели управления проектом перейдите в API, затем Webhooks (Вебхуки), затем Create webhook (Создать вебхук). Установите URL на ваш URL хука, метод на POST и выберите dataset и события триггеров.

Prismic

В панели управления перейдите в Settings (Параметры), затем Webhooks (Вебхуки), и добавьте ваш URL хука. Prismic вызывает его при каждой публикации документа.

Подключение cron задания или CI pipeline

Любой планировщик, который может выполнить HTTP запрос, подойдет:

# crontab: rebuild every night at 2am
0 2 * * * curl -fsS -X POST https://kpanel.kapsulehost.com/api/orbit/hooks/<your-token>

Для CI, хук развертывания - это самый простой вариант, когда вы хотите, чтобы ваш pipeline решил, будет ли развертывание. Это рекомендуемый подход для Bitbucket Pipelines, поскольку параметр требуемых проверок CI в Orbit работает с именами заданий GitHub Actions или pipeline GitLab, но не с Bitbucket.

Если вам нужно больше чем "развернуть head ветки", используйте токен API вместо хука. Orbit, затем Tokens (Токены), создает токены bearer с областью видимости для CI/CD с задокументированным REST API и готовым рабочим процессом GitHub Actions. Доступ к API включен в план Apex.

Перестроение по расписанию без хука

Если вам нужна только периодическая перестройка, вам вообще не нужен хук. Scheduled rebuild (Запланированная перестройка) в Settings (Параметры), раздел Runtime (Время выполнения), автоматически перестраивает production каждый час, 6 часов, 12 часов, ежедневно, через день или еженедельно. Это создано специально для случаев управляемых CMS сайтов и там нет никакого секретного URL для защиты.

Проверка активности хука

Каждая строка хука показывает, сколько раз он был использован и когда в последний раз, в форме "Used 14 times, last 3 Jul" (Использовано 14 раз, последний раз 3 июля). Это самый быстрый способ убедиться, что ваша CMS действительно вызывает хук, когда вы думаете, что она это делает.

Если счетчик не увеличивается, проблема находится на вызывающей стороне: проверьте, что метод POST, URL точен, и интеграция не молча не срабатывает с ошибкой TLS или брандмауэра.

Удаление хука

Нажмите Delete hook (Удалить хук) в строке и подтвердите. Диалоговое окно предупредит, что любой сервис, который его использует, перестанет работать, что именно и происходит.

Нет способа повернуть токен хука на месте. Если URL утечет, вы удаляете хук и создаете новый, затем обновляете каждую систему, которая использовала старый URL. Удаление вступает в силу немедленно, поэтому спланируйте замену до удаления, а не после.

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

Ничего не происходит, когда я вызываю хук. Проверьте, что метод POST. Проверьте URL символ за символом, включая токен. Проверьте счетчик использования хука на вкладке Hooks: если он не увеличивается, запрос так и не пришел.

Хук возвращает ошибку о последнем commit'е. Orbit не смог прочитать head ветки у вашего поставщика git. Переподключите поставщика из Orbit, затем New project (Новый проект), затем Reconnect (Переподключить), и подтвердите, что репозиторий по-прежнему доступен.

Хук возвращает ошибку о целевой среде. Среда, на которую указывал хук, больше не существует, скорее всего потому, что была удалена staging среда. Удалите хук и создайте новый для активной среды.

Хук срабатывает, но развертывание такое же, как в последний раз. Это поведение дедупликации: head ветки не изменился, так что нечего новое строить. Отправьте commit, или используйте Deploy now (Развернуть сейчас), если вы специально хотите пересстроить тот же commit.

Дополнительное чтение

Deploying Your Project для защитных механизмов развертывания и того, какие из них обходят хуки
Connecting a Bitbucket Repo для случая CI gating, который решают хуки
Environment Variables, поскольку развертывание, инициированное хуком, читает ту же конфигурацию, что и любое другое