Настройка рабочего процесса GitHub Actions

  • 10 мин

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

Настройка рабочих процессов для выполнения запланированных событий

Как упоминалось ранее, вы можете настроить запуск рабочих процессов при выполнении определенного действия на GitHub, если событие происходит за пределами GitHub или в запланированное время. Это schedule событие позволяет активировать рабочий процесс для выполнения в определенное время в формате UTC с помощью синтаксиса cron POSIX. Этот синтаксис cron имеет пять полей *. Каждое поле представляет единицу времени.

Схема пяти полей времени для планирования события в файле рабочего процесса.

Например, если вы хотите запустить рабочий процесс каждые 15 минут, schedule событие будет выглядеть следующим образом:

on:
  schedule:
    - cron:  '*/15 * * * *'

Если вы хотите запустить рабочий процесс каждое воскресенье в 3:00, событие schedule будет выглядеть следующим образом:

on:
  schedule:
    - cron:  '0 3 * * SUN'

Вы также можете использовать операторы для указания диапазона значений или для обращения к запланированному рабочему процессу. Кратчайший интервал, с которым можно запускать запланированные рабочие процессы, составляет 5 минут. Они запускаются в соответствии с последней фиксацией базовой ветви или ветви по умолчанию.

Настройка запуска рабочих процессов для вызванных событий

Помимо запланированных событий, вы можете вручную запустить рабочий процесс с помощью события workflow_dispatch. Это событие позволяет запустить рабочий процесс с помощью REST API GitHub или нажав кнопку "Выполнить рабочий процесс " на вкладке "Действия " в репозитории на GitHub. С помощью workflow_dispatch вы можете выбрать ветвь, на которой хотите запустить рабочий процесс, и задать необязательные inputs, которые GitHub представляет в виде элементов формы в пользовательском интерфейсе.

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'     
        required: true
        default: 'warning'
      tags:
        description: 'Test scenario tags'

Кроме workflow_dispatch, вы можете использовать API GitHub для активации события веб-перехватчика с именем repository_dispatch. Это событие позволяет активировать рабочий процесс для действий, происходящих за пределами GitHub. Он по сути служит как HTTP-запрос к вашему репозиторию, запрашивая GitHub запуск рабочего процесса на основе действия или веб-перехватчика. При использовании этого ручного события необходимо выполнить два действия: отправить запрос POST конечной точке GitHub /repos/{owner}/{repo}/dispatches, указав имена событий веб-перехватчика в тексте запроса, и настроить рабочий процесс для использования этого события repository_dispatch.

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/dispatches \
  -d '{"event_type":"event_type"}'

on:
  repository_dispatch:
    types: [opened, deleted]

Настройка запуска рабочих процессов для событий веб-перехватчика

Наконец, можно настроить запуск рабочего процесса при возникновении конкретных событий веб-перехватчика на сайте GitHub. Вы можете активировать большинство событий веб-хука в результате нескольких действий. Если для вебхука существует несколько действий, можно указать тип действия для запуска рабочего процесса. Например, можно запустить рабочий процесс для события check_run, но только для видов активности rerequested или requested_action.

on:
  check_run:
    types: [rerequested, requested_action]

Отправка из репозитория

repository_dispatch — это настраиваемое событие в GitHub Actions, которое позволяет внешним системам (или даже другим рабочим процессам GitHub) вручную активировать рабочие процессы путем отправки запроса POST в API GitHub. Она обеспечивает гибкую автоматизацию и интеграцию с внешними инструментами, скриптами или системами, которые должны запускать рабочие процессы в репозитории.

Случаи использования

  • Активация рабочих процессов из внешних средств CI/CD.

  • Координировать развертывание с несколькими репозиториями (например, репозиторий A завершает сборку → триггерит репозиторий B).

  • Запустите автоматизацию на основе внешних событий (веб-перехватчики, оповещения мониторинга, задания CRON за пределами GitHub).

  • Выполнение последовательных рабочих процессов между репозиториями или внутри монорепозиториев.

Пример рабочего процесса, отслеживающего событие repository_dispatch

name: Custom Dispatch Listener

on:
  repository_dispatch:
    types: [run-tests, deploy-to-prod]  # Optional filtering

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Echo the payload
        run: |
          echo "Event type: ${{ github.event.action }}"
          echo "Payload value: ${{ github.event.client_payload.env }}"

Ключевые элементы:

  • типы: опция необязательна. Определяет пользовательские типы событий, такие как run-tests, deploy-to-prodи т. д.

  • github.event.client_payload. Доступ к любым другим пользовательским данным, переданным в событии отправки.

  • github.event.action: имя отправленного типа события.

Активация события с помощью API

Необходимо отправить запрос POST в конечную точку REST API GitHub версии 3:

POST https://api.github.com/repos/OWNER/REPO/dispatches

Авторизация

  • Требуется личный токен доступа (PAT) с правами доступа к репозиторию.
  • Для организаций убедитесь, что установлены необходимые параметры доступа для вашего токена.

Пример структуры команд

curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"run-tests","client_payload":{"env":"staging"}}'

Структура полезных данных

{
  "event_type": "run-tests",
  "client_payload": {
    "env": "staging"
  }
}

Параметры

Поле Тип Описание Обязательно
event_type струна Настраиваемое имя события. Это имя сопоставляется со значением типов в триггере рабочего процесса Да
client_payload объект Произвольный JSON-объект для отправки пользовательских данных в рабочий процесс (github.event.client_payload) нет

разбивка параметров Repository_dispatch

При выполнении запроса POST в конечную точку API GitHub необходимо передать текст JSON с двумя основными параметрами:

  • тип события
  • клиентский_пакет_данных
тип события

Требуемая настраиваемая строка, определяемая вами. GitHub обрабатывает это значение как действие или тип отправки. Он используется для идентификации активации рабочего процесса и фильтрации рабочих процессов, которые следят за определёнными типами.

  • Формат:

    • Тип: строка
    • Пример: "deploy", "run-test", "sync-db", "build-docker"

  • Использование в рабочем процессе: используется для прослушивания определенных типов событий и доступа к значению внутри рабочего процесса. Это помогает повторно использовать один рабочий процесс для нескольких целей и делает автоматизацию более упорядоченной и управляемой событиями.

  • Пример:

- name: Print event type
  run: echo "Event type: ${{ github.event.action }}"
клиентский_пакет_данных

Объект JSON бесплатной формы, позволяющий отправлять пользовательские данные вместе с отправкой. Вы определяете структуру и она доступна внутри рабочего процесса.

  • Формат:

    • Тип: объект
    • Пользовательские ключи и значения

  • Использование в рабочем процессе: этот объект используется для развертываний с несколькими средами, версий или передачи контекста из другой системы или конвейера и включает параметризованные рабочие процессы, аналогичные входным аргументам.

  • Пример:

- name: Show payload values
  run: |
    echo "Environment: ${{ github.event.client_payload.env }}"
    echo "Version: ${{ github.event.client_payload.version }}"
Пример разбивки нагрузки
{
  "event_type": "deploy-to-prod",
  "client_payload": {
    "env": "production",
    "build_id": "build-456",
    "initiator": "admin_user",
    "services": ["web", "api", "worker"]
  }
}

Использование условных ключевых слов

Используя файл рабочего процесса, можно получить доступ к сведениям о контексте и вычислить выражения. Хотя выражения часто используются с условным ключевым словом if в файле рабочего процесса для определения того, следует ли выполнять шаг или нет, вы можете использовать любой поддерживаемый контекст и выражение для создания условного выражения. Важно знать, что при использовании условных условий в рабочем процессе необходимо использовать конкретный синтаксис ${{ <expression> }}. Этот синтаксис сообщает GitHub оценивать выражение, а не рассматривать его как строку.

Например, рабочий процесс, использующий условие if, для проверки, соответствует ли github.ref (ветвь или ссылка тега, активировавшая запуск рабочего процесса) refs/heads/main. Чтобы продолжить, рабочий процесс будет выглядеть примерно так:

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      ...

Обратите внимание, что в этом примере в синтаксисе отсутствует элемент ${{ }}. При использовании некоторых выражений, таких как условный if , можно опустить синтаксис выражения. GitHub автоматически оценивает некоторые из этих общих выражений. Вы всегда можете включить их, если забыли, какие выражения будут автоматически оцениваться в GitHub.

Дополнительные сведения о синтаксисе и выражениях рабочих процессов см. в описании синтаксиса рабочего процесса для GitHub Actions.

Отключение и удаление рабочих процессов

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

Снимок экрана: отключение рабочего процесса на GitHub.

Отключение рабочего процесса может оказаться полезным в некоторых из следующих ситуаций:

  • Из-за ошибки в рабочем процессе возникает слишком много запросов или неправильные запросы, которые отрицательно влияют на внешние службы.
  • Вы хотите временно приостановить рабочий процесс, который не является критическим и потребляет слишком много минут в вашей учетной записи.
  • Вы хотите приостановить рабочий процесс, отправляющий запросы в службу, которая отключена.
  • Вы работаете с форком и вам не нужны все функции некоторых рабочих процессов, которые он включает, например, запланированные рабочие процессы.

Вы также можете отменить выполнение рабочего процесса, которое выполняется в пользовательском интерфейсе GitHub на вкладке "Действия " или с помощью конечной точки DELETE /repos/{owner}/{repo}/actions/runs/{run_id}API GitHub. Помните, что при отмене выполнения рабочего процесса GitHub отменяет все его задания и шаги в рамках этого запуска.

Использование шаблонного рабочего процесса организации

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

Эти рабочие процессы можно найти, перейдя на вкладку "Действия " репозитория в организации, выбрав новый рабочий процесс, а затем найдите раздел шаблона рабочего процесса организации под названием "Рабочие процессы, созданные по имени организации". Например, организация под названием Mona имеет шаблон рабочего процесса, как показано здесь.

Снимок экрана рабочего процесса организации шаблона под названием «Приветствие и сортировка», созданного Моной.

Использование конкретных версий действия

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

steps:    
  # Reference a specific commit
  - uses: actions/setup-node@c46424eee26de4078d34105d3de3cc4992202b1e
  # Reference the major version of a release
  - uses: actions/setup-node@v1
  # Reference a minor version of a release
  - uses: actions/setup-node@v1.2
  # Reference a branch
  - uses: actions/setup-node@main

Некоторые ссылки более безопасны, чем другие. Например, указание на конкретную ветвь запускает это действие с последними изменениями из этой ветви, которые могут вам понадобиться или не понадобиться. Ссылаясь на конкретный номер версии или SHA-хэш фиксации, вы более точно указываете версию выполняемого действия. Для повышения стабильности и безопасности рекомендуется использовать агент работоспособности системы фиксации для действия, запущенного в рамках рабочих процессов.