Современная разработка часто требует интеграции систем непрерывной интеграции и доставки (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.
- Перейдите в настройки вашего профиля GitHub.
- Выберите Developer settings → Personal access tokens → Tokens (classic).
- Создайте новый токен (Generate new token).
- Установите права доступа (Permissions): Для запуска
repository_dispatchвам необходим токен с правами:metadata: readcontents: read and write- Иногда может потребоваться
workflow(для некоторых сложных сценариев).
- Сохраните токен сразу после генерации, так как он будет показан только один раз.
Шаг 4: Запуск Workflow через Postman (API)
После настройки Workflow и получения токена можно выполнять запуск. Для этого используется стандартный API-клиент, например, Postman.
1. Метод и URL:
Используйте метод POST на следующий URL:
https://api.github.com/repos/<ВАШ_ПОЛЬЗОВАТЕЛЬ>/<ИМЯ_РЕПОЗИТОРИЯ>/dispatches
2. Заголовки (Headers):
Необходимо установить как минимум два заголовка:
| Key | Value |
Accept | application/vnd.github.v3+json |
Authorization | token <ВАШ_PAT_ТОКЕН> |
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.
