Очередь CI — не лучший способ проверять YAML. Каждый пуш запускает workflow, а результат приходится ждать минутами. act читает каталог .github/workflows и выполняет те же задания локально в Docker-контейнерах. Это ускоряет отладку, но не заменяет GitHub-hosted runner: окружение и часть функций отличаются.

Как работает act и когда он полезен

Утилита разбирает workflow, строит граф зависимостей между заданиями и запускает контейнеры через Docker API. Внутри выставляются переменные окружения, похожие на переменные GitHub, монтируется рабочая копия репозитория и эмулируются основные события: push, pull_request, workflow_dispatch, schedule.

Практическая польза: быстро найти опечатку в выражении ${{ }}, проверить matrix и отработать установку зависимостей, не засоряя историю коммитов сообщениями «fix ci». Он же может заменить Makefile для повторяющихся задач.

Важное условие — Docker. Без него act не запустится, а на macOS и Windows контейнеры всё равно будут Linux-контейнерами. Задания с runs-on: macos-latest или windows-latest локально не исполняются.

Установка и проверка Docker

sudo apt install ./act_*_amd64.deb
act --version
docker info
sudo usermod -aG docker "$USER"
newgrp docker

Готовый .deb берут из GitHub Releases. Если пакета нет, подойдут go install github.com/nektos/act@latest или brew install act. После добавления в группу docker перелогиньтесь либо выполните newgrp docker. Команда docker info должна показать сервер без ошибки доступа к сокету.

Не запускайте act от root без необходимости: контейнер видит рабочую копию, ваши файлы и настройки Git. Для обычных задач достаточно прав группы docker.

Первый запуск: список, dry-run и один job

cd ~/projects/example
act -l
act -n
act push -W .github/workflows/ci.yml -j test

act -l показывает workflow и задания. act -n проверяет корректность workflow без создания контейнеров. -W указывает файл, -j — имя задания. Без события act считает запущенным push; для PR используйте act pull_request -W .github/workflows/ci.yml.

Запускать команды нужно из корня репозитория: пути и actions/checkout рассчитаны на такую структуру. Нестандартный каталог задаётся через -W.

Рабочий пример workflow

name: ci
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: |
          python -m venv .venv
          .venv/bin/pip install -r requirements.txt
          .venv/bin/pytest -q

Файл не специфичен для act: он же работает на GitHub. Виртуальное окружение добавлено намеренно — в свежих Ubuntu системный Python помечен как externally managed, и прямой pip install может упасть.

Локальный прогон: act -W .github/workflows/ci.yml -j test. Первый запуск скачивает образ runner и занимает несколько минут; повторные быстрее. Если setup-python не находит версию, проверьте доступ к GitHub и место на диске.

Секреты, переменные и события

act -s GITHUB_TOKEN="$(gh auth token)" -W .github/workflows/ci.yml
act --secret-file .secrets --var-file .vars
act workflow_dispatch -W .github/workflows/release.yml --input version=1.4.0

Секреты не подставляются автоматически. -s NAME без значения запрашивает секрет в защищённом вводе и не пишет его в историю. Файлы .secrets и .vars используют формат .env, поэтому добавьте их в .gitignore. Для переменных ${{ vars.NAME }} есть --var и --var-file.

Событие уточняется файлом payload: act pull_request -e event.json. В нём задают head.ref и base.ref, если workflow читает эти поля. Для ручного запуска inputs передаются через --input или --input-file.

Шаги, которые нельзя выполнять локально, помечайте условием:

- name: Deploy to production
  if: ${{ !env.ACT }}
  run: ./deploy.sh

act выставляет переменную ACT, поэтому деплой, уведомления и публикация пакетов пропускаются. Для задания целиком проверяют github.event.act и передают {"act": true} через -e.

.actrc, образы и артефакты

--container-architecture=linux/amd64
-P ubuntu-latest=catthehacker/ubuntu:act-latest
--artifact-server-path=.artifacts
--action-offline-mode

Файл .actrc избавляет от длинных команд: один аргумент на строку, комментарии не поддерживаются. На ARM-машинах архитектура linux/amd64 часто обязательна, иначе часть actions не запустится.

Образ catthehacker/ubuntu:act-latest ближе к окружению GitHub, чем минимальный по умолчанию, но весит сотни мегабайт. Следите за местом: docker system df показывает размеры, docker image prune удаляет неиспользуемые слои. Флаг --reuse оставляет контейнер после успешного прогона, а --rm удаляет его и после сбоя.

Артефакты работают только при явно запущенном сервере: --artifact-server-path=.artifacts. Каталог добавьте в .gitignore. Режим --action-offline-mode ускоряет повторные запуски, но не отменяет первую загрузку образов.

Отладка и типичные ошибки

act -v -W .github/workflows/ci.yml -j test
docker ps -a --filter "name=act-"
docker logs <container_id>
docker system df

Флаг -v печатает подробный журнал: какой образ выбран, какие переменные переданы, где сбой. Если контейнер остался после падения, ищите его через docker ps -a, а вывод — через docker logs.

Частые причины: permission denied на /var/run/docker.sock — пользователь не в группе docker; manifest unknown — опечатка в -P; node: not found — слишком минимальный образ; Resource not accessible — не передан GITHUB_TOKEN. Проверьте также переводы строк: скрипт с CRLF может падать на shebang.

Ограничения и чек-лист

  • Только Linux-контейнеры; macOS и Windows jobs не выполняются.
  • Не реализованы OIDC, concurrency, job.permissions, timeout-minutes и continue-on-error.
  • Step summary, аннотации и problem matcher игнорируются.
  • Предустановленный софт отличается: фиксируйте версии в workflow.
  • Секреты, переменные и артефакты подключаются вручную.
  • Не запускайте act на непроверенных PR: workflow выполняет произвольный код и видит рабочую копию.

Минимальный чек-лист: Docker работает без sudo; репозиторий открыт в корне; act -l видит нужный workflow; образ для ubuntu-latest задан в .actrc; секреты лежат вне Git; деплой-шаги закрыты условием !env.ACT.

Итог

act сокращает цикл проверки с минут до секунд и хорошо ловит ошибки YAML, выражений и shell-шагов. Но финальную проверку оставляйте GitHub Actions: только там работают реальные permissions, OIDC и полный набор runner. Начните с act -l и одного задания, затем добавьте .actrc и файл секретов.

Насколько публикация полезна?

Нажмите на звезду, чтобы оценить!

Средняя оценка 0 / 5. Количество оценок: 0

Оценок пока нет. Поставьте оценку первым.

Поделиться: Telegram ВКонтакте