Удаленный запуск GitHub Actions: Полное руководство по workflow_dispatch и REST API

GitHub Actions — это краеугольный камень современной CI/CD автоматизации. Он позволяет настроить сложнейшие процессы сборки, тестирования и развертывания, привязывая их к стандартным событиям, таким как push или pull_request. Однако в сложных инфраструктурах часто возникает необходимость запустить воркфлоу извне: из стороннего веб-сервиса, локального скрипта или пользовательского интерфейса.

Именно для таких сценариев GitHub предусмотрел событие workflow_dispatch, которое в сочетании с GitHub REST API дает полный контроль над удаленным запуском ваших конвейеров.

• Что такое workflow_dispatch?
• Шаг 1: Настройка аутентификации (Personal Access Token)
• Шаг 2: Формирование запроса REST API
  • 1. URL запроса
  • 2. Обязательные Заголовки (Headers)
  • 3. Тело Запроса (Body)
• Шаг 3: Отправка и проверка результата

Что такое workflow_dispatch?

workflow_dispatch — это специальный тип триггера, который позволяет инициировать рабочий процесс вручную или программно. Если вы добавите его в секцию on вашего YAML-файла, вы сразу получите две возможности:

1. Ручной запуск через интерфейс GitHub, где можно выбрать ветку и ввести параметры.
2. Удаленный запуск с помощью HTTP POST-запроса.

Ключевым преимуществом этого триггера является его способность принимать входные параметры (inputs). Вы можете определить переменные (строки, булевы значения), которые будут переданы в воркфлоу и использованы на любом его этапе.

Шаг 1: Настройка аутентификации (Personal Access Token)

Для взаимодействия с GitHub API требуется надежный и безопасный метод аутентификации. Оптимальным решением является использование Personal Access Token (PAT).

1. Создание PAT: Перейдите в настройки вашего аккаунта GitHub в раздел Developer Settings > Personal Access Tokens.
2. Настройка разрешений: При генерации нового токена обязательно предоставьте ему необходимое разрешение. Для удаленного запуска Actions требуется право workflow (или actions: read and write для более старых версий токенов) для целевого репозитория. Это критически важно для авторизации запроса на запуск.

Сгенерированный PAT будет использоваться в заголовке Authorization вашего HTTP-запроса.

Шаг 2: Формирование запроса REST API

Для удаленного запуска воркфлоу используется метод POST по строго определенному адресу. Для отправки запроса удобно использовать такой инструмент, как Postman.

1. URL запроса

Используйте следующий шаблон URL, заменяя переменные на конкретные значения вашего проекта:

POST /repos/{owner}/{repo}/actions/workflows/{workflow_file_name}/dispatches

• {owner}: Имя пользователя или организации.
• {repo}: Название репозитория.
• {workflow_file_name}: Точное имя вашего YAML-файла воркфлоу (например, ci_build.yml).

2. Обязательные Заголовки (Headers)

Успешный API-вызов требует корректной передачи аутентификационных данных и версии API:

3. Тело Запроса (Body)

Тело запроса должно быть в формате JSON и содержать как минимум два поля:

• ref: Имя ветки, в которой находится YAML-файл, который вы хотите запустить (например, "main").
• inputs: Объект, содержащий пары ключ-значение для всех входных параметров, определенных в вашем воркфлоу.

Пример JSON-тела для Postman:

JSON

{
  "ref": "main",
  "inputs": {
    "title": "Удаленный запуск через Postman",
    "environment": "production_server" 
    // Ключи "title" и "environment" должны совпадать с именами в секции inputs YAML-файла.
  }
}

Шаг 3: Отправка и проверка результата

После того, как вы сформировали запрос (URL, заголовки, тело), отправьте его.

Успешный ответ:

Если все параметры указаны верно, GitHub вернет статус 204 No Content. Это означает, что запрос принят, и воркфлоу поставлен в очередь на выполнение. В теле ответа не будет данных, поскольку это асинхронный запуск.

Проверка:

Сразу после получения 204 No Content вы можете перейти на вкладку Actions в вашем репозитории и увидеть, что рабочий процесс начал выполнение. В логах выполнения вы сможете убедиться, что все переданные через секцию inputs значения корректно попали в среду выполнения.

Таким образом, использование workflow_dispatch и REST API позволяет создавать полностью автоматизированные, внешние системы, которые могут управлять вашими процессами CI/CD на GitHub, интегрируя их в любой сегмент вашей инфраструктуры.

Автор: Александр Сокирка

Занимаюсь веб разработкой с 2007 года. Имею большой опыт в веб-дизайне и разработке сайтов. Являюсь автором YouTube канала Быть Программистом. Основатель бренда Aletheme и автор тем для WordPress на маркетплэйсе Envato. С 2017 года занимаюсь обучением людей желающим стать программистами. Мои обучающие программы можно найти на этом сайте или на Udemy.