Автоматизация в GitHub

Workflow: файл, запуск, jobs и steps

Workflow в GitHub Actions — это YAML-файл в репозитории, который описывает автоматизированный процесс: когда запускаться, на какой машине выполнять работу и какие команды или actions вызывать. Минимальная физика такая: файл лежит в .github/workflows, имеет расширение .yml или .yaml, GitHub читает его при событии и создает workflow run — конкретный запуск этого workflow.

Один репозиторий обычно содержит несколько workflow: например, ci.yml для проверки PR, release.yml для публикации релиза, deploy.yml для деплоя. Это не «один большой pipeline на весь проект», а набор независимых автоматизаций, которые GitHub показывает во вкладке Actions.

Минимальный workflow-файл

name: CI
run-name: CI for ${{ github.ref_name }} by @${{ github.actor }}

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

jobs:
  test:
    name: Test app
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

Здесь name — имя workflow как сущности. Оно видно в левом списке вкладки Actions. Если name не указан, GitHub показывает путь к файлу относительно корня репозитория, например .github/workflows/ci.yml.

run-name — имя конкретного запуска. Это удобно, когда один и тот же workflow запускается много раз: по веткам, PR, ручным параметрам, релизам. В run-name можно использовать expressions и контексты github и inputs. Например, ручной deploy может называться Deploy production by @alex, а CI для PR — по заголовку PR или по вашей явной строке. Подробнее о выражениях — в статье \Contexts и expressions\.

on описывает trigger: событие, которое создает run. В примере workflow запускается на push в main, на pull_request в main и вручную через workflow_dispatch. Синтаксис событий быстро становится отдельной темой: activity types, filters по branches/tags/paths, schedule, workflow_call, workflow_run. Для этого есть отдельная статья \Events и filters\.

Jobs: крупные блоки выполнения

jobs — словарь job’ов. Ключ test в примере — это job_id, внутренний идентификатор. Его используют в needs, outputs и ссылках между job’ами. name: Test app внутри job — человекочитаемое имя, которое GitHub показывает в UI.

Каждый job выполняется на runner. Ключ runs-on: ubuntu-latest говорит GitHub поставить job в очередь на подходящий GitHub-hosted runner с Ubuntu. Можно выбрать Windows, macOS, larger runner или self-hosted runner через labels и runner groups. Базовая тема runner’ов вынесена в \GitHub-hosted runners\ и \Self-hosted runners\.

По умолчанию job’ы без зависимостей запускаются параллельно. Если нужен порядок, используется needs:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: npm test

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - run: npm run build

Такой workflow читается как граф: build ждет успешного завершения test. Условия, if, continue-on-error, status functions и timeout’ы — это уже материал статьи \Jobs, dependencies и conditions\.

Steps: команды и actions

Step — единица работы внутри job. Steps выполняются последовательно на одном и том же runner, поэтому результат одного шага может быть доступен следующему: файлы остаются в workspace, установленные зависимости остаются на машине до конца job, переменные можно передавать через специальные workflow commands.

У step есть два основных режима:

- name: Run shell command
  run: npm test

run запускает shell-команду. На Linux и macOS это обычно bash, на Windows — PowerShell, если не переопределить shell. Такой step подходит для команд проекта: npm ci, go test ./..., cargo test, docker build.

- name: Checkout repository
  uses: actions/checkout@v4

uses вызывает action — переиспользуемый блок логики. Частые примеры: actions/checkout, setup-actions для языков, загрузка артефактов, публикация пакетов. Здесь важны версия и доверие к action: pinning, Marketplace и maintenance рассматриваются в \Marketplace actions и pinning\.

В одном step нельзя одновременно использовать run и uses: либо команда, либо action. Для action часто задают with, а для команд — env, working-directory, shell.

- name: Build frontend
  working-directory: apps/web
  env:
    NODE_ENV: production
  run: npm run build

Переменные окружения, repository variables и secrets не стоит смешивать в одну кучу. env — это runtime-переменная для процесса, vars — конфигурационные значения GitHub, secrets — чувствительные значения с маскированием в логах. Смотри \Variables, env и secrets\.

Что GitHub показывает в Actions UI

Когда событие подходит под on, GitHub создает workflow run. Во вкладке Actions вы обычно видите:

• список workflow слева — по name или имени файла;
• список runs выбранного workflow — по run-name или автоматически выбранному названию события;
• summary конкретного run: статус, actor, branch/tag, commit SHA, jobs, граф зависимостей;
• logs по каждому job и step;
• artifacts и summaries, если workflow их создает.

GitHub также добавляет служебные шаги в логи job: Set up job и Complete job. В Set up job для GitHub-hosted runner можно увидеть образ runner’а и детали окружения. Это полезно при расследовании «у меня локально работает, а в CI нет». Для системного подхода к поломкам есть \Monitoring и troubleshooting\.

Важно различать workflow как файл и workflow run как конкретное исполнение. Файл ci.yml может не меняться месяцами, но runs будут появляться на каждый push, PR или ручной запуск. Run фиксирует commit, event payload, actor, выбранные inputs, статусы job’ов и логи. Поэтому при разборе инцидента смотрят не только YAML в текущей ветке, а конкретный run и commit, на котором он выполнялся.

Практические детали, которые экономят время

Хороший workflow начинается с понятных имен. name: CI нормально для маленького проекта, но в монорепозитории лучше разделять Web CI, API CI, Release packages. Для job’ов тоже стоит писать name, если job_id технический: test-node-22 в YAML может отображаться как Node.js 22 tests.

run-name особенно полезен для ручных запусков:

name: Deploy
run-name: Deploy ${{ inputs.environment }} by @${{ github.actor }}

on:
  workflow_dispatch:
    inputs:
      environment:
        description: Target environment
        required: true
        type: choice
        options: [staging, production]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to ${{ inputs.environment }}"

Такой run в списке будет читаться как операция, а не как безликое «Deploy». Но не пытайтесь запихнуть в run-name данные, которые вычисляются в середине job: имя run определяется до выполнения steps.

Еще одна привычка: держать workflow маленьким на уровне ответственности. CI, release и production deploy могут ссылаться на общие pieces, но у них разные события, права, environments и риски. Для переиспользования целых job/pipeline есть \Reusable workflows\; для упаковки набора steps в action — \Composite actions\.

See also

• \Events и filters\ — все способы запуска workflow и фильтрации событий.
• \Jobs, dependencies и conditions\ — граф job’ов, needs, if и статусы.
• \Contexts и expressions\ — ${{ }}, contexts и момент вычисления выражений.
• \Permissions и GITHUB_TOKEN\ — права workflow и минимизация доступа.
• \GitHub-hosted runners\ — какие машины выполняют job’ы.
• \Workflow commands и summaries\ — передача данных, аннотации и summary в UI.