Запуск GitHub Actions Workflow извне: Полное руководство по repository_dispatch и API

Современная разработка часто требует интеграции систем непрерывной интеграции и доставки (CI/CD) с внешними приложениями. Стандартные триггеры GitHub Actions, такие как push или pull_request, не всегда подходят, когда вам нужно запустить рабочий процесс из CRM, внутреннего сервиса или даже мобильного приложения. Для этих целей GitHub предлагает мощный и гибкий механизм – repository_dispatch.

Эта статья поможет вам понять, как настроить ваш репозиторий для приема внешних запросов и как использовать API, например, через Postman, для запуска ваших Workflow.

• Что такое repository_dispatch и почему он нужен?
• Шаг 1: Настройка Workflow для приема внешних событий
• Шаг 2: Передача данных в Workflow
• Шаг 3: Генерация Personal Access Token (PAT)
• Шаг 4: Запуск Workflow через Postman (API)

Что такое repository_dispatch и почему он нужен?

repository_dispatch — это тип события GitHub Actions, который позволяет вам вызвать Workflow, отправив HTTP POST-запрос на специальный URL-адрес GitHub API.

Ключевое отличие repository_dispatch от других способов ручного запуска (workflow_dispatch):

• workflow_dispatch создает кнопку запуска прямо в интерфейсе GitHub Actions. Он предназначен для ручного запуска пользователем.
• repository_dispatch не создает никаких элементов в интерфейсе. Он разработан исключительно для программного, внешнего запуска из любого приложения, которое может отправлять HTTP-запросы.

Таким образом, если ваша цель — автоматизировать запуск CI/CD при наступлении события в совершенно другой системе, repository_dispatch является идеальным решением.

Шаг 1: Настройка Workflow для приема внешних событий

Чтобы ваш Workflow ожидал внешнего запуска, в его YAML-файле необходимо указать соответствующий триггер.

В разделе on: замените (или добавьте) стандартный триггер на repository_dispatch. Обязательно укажите параметр types.

Пример конфигурации:

on:
  repository_dispatch:
    types: [запуск_извне, проверка_данных]

Параметр types является критически важным. Он выступает в роли «ключа» или «фильтра». Вы можете определить несколько типов, и при внешнем вызове API вы должны указать один из этих типов. Если тип не совпадает, Workflow запущен не будет.

Шаг 2: Передача данных в Workflow

Одним из главных преимуществ внешнего запуска является возможность передавать пользовательские данные. Эти данные используются для динамического поведения Workflow (например, для указания среды развертывания или версии приложения).

Передаваемые данные доступны в Workflow через специальный контекст github.event.client_payload.

Пример извлечения данных в шаге:

Если вы передадите JSON-объект { "release_title": "v1.2.0", "environment": "production" }, вы сможете получить заголовок релиза следующим образом:

- name: Использование внешних данных
  run: echo "Заголовок релиза: ${{ github.event.client_payload.release_title }}"

Шаг 3: Генерация Personal Access Token (PAT)

Для авторизованного запуска Workflow через API требуется специальный токен. Вы не можете использовать обычный пароль GitHub.

1. Перейдите в настройки вашего профиля GitHub.
2. Выберите Developer settings → Personal access tokens → Tokens (classic).
3. Создайте новый токен (Generate new token).
4. Установите права доступа (Permissions): Для запуска repository_dispatch вам необходим токен с правами:
   • metadata: read
   • contents: read and write
   • Иногда может потребоваться workflow (для некоторых сложных сценариев).
5. Сохраните токен сразу после генерации, так как он будет показан только один раз.

Шаг 4: Запуск Workflow через Postman (API)

После настройки Workflow и получения токена можно выполнять запуск. Для этого используется стандартный API-клиент, например, Postman.

1. Метод и URL:

Используйте метод POST на следующий URL:

https://api.github.com/repos/<ВАШ_ПОЛЬЗОВАТЕЛЬ>/<ИМЯ_РЕПОЗИТОРИЯ>/dispatches

2. Заголовки (Headers):

Необходимо установить как минимум два заголовка:

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

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

• event_type: Должен совпадать с одним из types, указанных в вашем YAML-файле (например, запуск_извне).
• client_payload: Объект, содержащий любые данные, которые вы хотите передать в Workflow.

Пример JSON-тела:

{
  "event_type": "запуск_извне",
  "client_payload": {
    "initiator": "External API Caller",
    "deployment_id": 1001
  }
}

После отправки запроса, если все настроено верно, вы получите ответ с кодом 204 No Content, который означает успешное принятие запроса. Ваш Workflow немедленно появится в списке действий GitHub Actions и начнет выполнение, используя переданные вами данные.

Использование repository_dispatch позволяет вам строить по-настоящему сложные, интегрированные и полностью автоматизированные CI/CD-пайплайны, которые являются краеугольным камнем современного DevOps.

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

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