Как запустить GitHub Actions локально

GitHub Actions помогает автоматизировать такие задачи, как сборка, тестирование и развертывание в вашем репозитории GitHub.

Одним щелчком мыши вы можете опубликовать готовый код или пакет на npm, GitHub Pages, как образ docker, развернуть продакшен-код у облачного провайдера и так далее.

Проблемы начинаются, когда вы решаетесь испытать GitHub Actions. Это может занять много времени и обернуться головной болью. Сперва вам нужно локально изменить файл GitHub Actions, затем перенести локальный код в репозиторий GitHub и ждать результата.

Чтобы решить эту проблему, вы можете использовать act — инструмент командной строки (CLI) для тестирования и написания GitHub action («действия» GitHub) локально. Благодаря act вам не нужно будет коммитить / пушить свой локальный код в репозиторий GitHub. Вы сможете протестировать GitHub action локально, на своей машине.

В этой статье мы разберем:

Как установить act для работы с GitHub Actions

Инструмент act работает с Docker. Поэтому, прежде чем приступить к работе с act, сначала установите Docker в свою систему.

От редакции Techrocks: подробнее о Docker можно почитать, например, в обзорной статье «Docker: практическое руководство для начинающих».

Чтобы установить act, вам нужно выполнить следующую команду:

# Window
choco install act-cli

# MacOS
brew install act

# Linux
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Как настроить и инициализировать act

После успешной установки act на вашу машину нужно запустить его в вашем проекте.

Во время установки act спрашивает, какой размер образа Docker должен быть установлен: большой, средний или микро.

Образы Docker бывают разного размера; выбирать нужно соответственно нуждам проекта:

  • Docker Micro имеет размер 200 МБ. Такой образ годится для небольших проектов.
  • Размер образа Docker Medium — 500 МБ, его используют большие проекты.
  • Docker Large — 17 ГБ, его используют корпоративные проекты.

Act использует образ Docker для локального запуска GitHub action.

$ act

Вывод команды в терминале выглядит следующим образом:

$ test-github-actions git:(main) ✗ act
? Please choose the default image you want to use with act:
  - Large size image: ca. 17GB download + 53.1GB storage, you will need 75GB of free disk space, snapshots of GitHub Hosted Runners without snap and pulled docker images
  - Medium size image: ~500MB, includes only necessary tools to bootstrap actions and aims to be compatible with most actions
  - Micro size image: <200MB, contains only NodeJS required to bootstrap actions, doesn't work with all actions

Default image and other options can be changed manually in ~/.actrc (please refer to https://github.com/nektos/act#configuration for additional information about file structure) Micro
[Build Ghost and test theme/install] 🚀  Start image=node:16-buster-slim
INFO[0023] Parallel tasks (0) below minimum, setting to 1 
[Build Ghost and test theme/install]   🐳  docker pull image=node:16-buster-slim platform= username= forcePull=true
INFO[0031] Parallel tasks (0) below minimum, setting to 1 
[Build Ghost and test theme/install]   🐳  docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Build Ghost and test theme/install]   🐳  docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Build Ghost and test theme/install]   ☁  git clone 'https://github.com/vimtor/action-zip' # ref=v1.2
[Build Ghost and test theme/install]   ☁  git clone 'https://github.com/softprops/action-gh-release' # ref=v0.1.15
[Build Ghost and test theme/install] ⭐ Run Main actions/checkout@v4
[Build Ghost and test theme/install]   🐳  docker cp src=/home/officialrajdeepsingh/medium/test-github-actions/. dst=/home/officialrajdeepsingh/medium/test-github-actions
[Build Ghost and test theme/install]   ✅  Success - Main actions/checkout@v4
[Build Ghost and test theme/install] ⭐ Run Main Easy Zip Files
[Build Ghost and test theme/install]   🐳  docker cp src=/home/officialrajdeepsingh/.cache/act/vimtor-action-zip@v1.2/ dst=/var/run/act/actions/vimtor-action-zip@v1.2/
[Build Ghost and test theme/install]   🐳  docker exec cmd=[node /var/run/act/actions/vimtor-action-zip@v1.2/dist/index.js] user= workdir=
| Ready to zip "build/ home.txt" into example.zip
|   - build/
|   - home.txt
| 
| Zipped file example.zip successfully
[Build Ghost and test theme/install]   ✅  Success - Main Easy Zip Files
[Build Ghost and test theme/install] Cleaning up container for job install
[Build Ghost and test theme/install] 🏁  Job succeeded

В этом примере мы использовали микро-образ.

После загрузки образа из Docker-репозитория act запускает GitHub action.

Для настройки act генерирует файл ~/.actrc на вашей машине. Этот файл содержит имя образа Docker.

# .actrc
-P ubuntu-latest=node:16-buster-slim
-P ubuntu-22.04=node:16-bullseye-slim
-P ubuntu-20.04=node:16-buster-slim
-P ubuntu-18.04=node:16-buster-slim

Чтобы установить другие образы Docker, удалите файл ~/.actrc и повторно запустите act.

Возможная ошибка при инициализации

Из-за зависимости от Docker мы можем столкнуться с некоторыми ошибками при первой инициализации act CLI.

$ act

Выглядеть ошибка может следующим образом:

$ test-github-actions git:(main) ✗ act       
ERRO[0000] daemon Docker Engine socket not found and containerDaemonSocket option was not set 
? Please choose the default image you want to use with act:
  - Large size image: ca. 17GB download + 53.1GB storage, you will need 75GB of free disk space, snapshots of GitHub Hosted Runners without snap and pulled docker images
  - Medium size image: ~500MB, includes only necessary tools to bootstrap actions and aims to be compatible with most actions
  - Micro size image: <200MB, contains only NodeJS required to bootstrap actions, doesn't work with all actions

Default image and other options can be changed manually in ~/.actrc (please refer to https://github.com/nektos/act#configuration for additional information about file structure) Micro
[Build Ghost and test theme/install] 🚀  Start image=node:16-buster-slim
INFO[0305] Parallel tasks (0) below minimum, setting to 1 
[Build Ghost and test theme/install]   🐳  docker pull image=node:16-buster-slim platform= username= forcePull=true
Error: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

В приведенном коде вы видите ошибку «Cannot connect to the Docker daemon». Она возникает из-за демона Docker. Проще говоря, демон Docker не запущен. Проблема решается просто: нужно запустить Docker и повторно выполнить команду act.

Есть два способа запуска сервисов Docker:

  • Откройте десктопное приложение Docker в своем окне, и ваш сервис Docker будет запущен.
  • Запустите Docker с помощью команды systemctl start docker в Linux.

Проверить, запущен ли ваш Docker, можно с помощью следующей команды:

$ systemctl status docker

● docker.service - Docker Application Container Engine
     Loaded: loaded (/etc/systemd/system/docker.service; enabled; preset: enabled)
    Drop-In: /nix/store/fibzdkfv6in4xw39rm0c7bq4nadzisas-system-units/docker.service.d
             └─overrides.conf
     Active: active (running) since Mon 2024-02-26 12:38:37 IST; 3h 39min ago
TriggeredBy: ● docker.socket
       Docs: https://docs.docker.com
   Main PID: 1186 (dockerd)
         IP: 0B in, 0B out
         IO: 109.0M read, 152.0K written
      Tasks: 40
     Memory: 148.5M
        CPU: 1min 40.817s
     CGroup: /system.slice/docker.service
             ├─1186 /nix/store/7pzis8dkhs461kl1bg2fp0202dw6r5i5-moby-24.0.5/libexec/docker/dockerd --config-file=/nix/store/3rlv5f0zldcc120b01szywidl0qz9x4p-daemon.json
             └─1256 containerd --config /var/run/docker/containerd/containerd.toml

Feb 26 12:38:37 nixos dockerd[1256]: time="2024-02-26T12:38:37.532987858+05:30" level=info msg="containerd successfully booted in 0.016901s"
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.562515048+05:30" level=info msg="[graphdriver] using prior storage driver: overlay2"
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.564062690+05:30" level=info msg="Loading containers: start."
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.778478313+05:30" level=info msg="Default bridge (docker0) is assigned with an IP address 172.17.0.0/16. Daemon option --bip can be used to set a preferred IP address"
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.805931545+05:30" level=info msg="Loading containers: done."
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.828589904+05:30" level=info msg="Docker daemon" commit=v24.0.5 graphdriver=overlay2 version=24.0.5
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.828929197+05:30" level=info msg="Daemon has completed initialization"
Feb 26 12:38:37 nixos systemd[1]: Started Docker Application Container Engine.
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.841992729+05:30" level=info msg="API listen on /run/docker.sock"
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.841993669+05:30" level=info msg="API listen on /run/docker.sock"

Как использовать act

У инструмента act много опций, но мы рассмотрим только несколько наиболее важных. Чтобы просмотреть все опции, выполните команду act --help.

Вот некоторые функции act CLI, доступные при использовании опций:

  • События
  • Списки
  • Запуск определенных заданий
  • Граф
  • Переменные среды
  • Секреты

События

В act действие по умолчанию — это push. Это действие, опять же, по умолчанию, запускает только события push.

Запуск act с дефолтным событием push:

$ act

Вы можете изменить событие, передав второй аргумент — имя вашего действия. В нашем случае мы передадим pull_request.

$ act pull_request

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

Списки

Опция -l выводит список всех доступных заданий, которые вы записали в .github/workflows.

$ act -l

Вывод команды в терминале выглядит следующим образом:

$ act -l    
Stage  Job ID             Job name           Workflow name                  Workflow file      Events      
0      zip                zip                Convert files into Zip         build-project.yml  release     
0      request_test       request_test       Pull Request                   fork.yml           fork        
0      pull_request_test  pull_request_test  Pull Request                   issues.yml         issues      
0      show               show               Convert files into Zip folder  test.yml           pull_request

Запуск определенных заданий

С помощью опции --job вы можете запускать определенные задания из ваших workflows.

Следите за тем, чтобы имя задания было уникальным, иначе будут запущены все задания с таким же именем в вашем workflow. Если вы не можете передать событие по умолчанию, запустите событие push.

Синтаксис:

act --job <имя-вашего-задания>

Допустим, мы запускаем конкретное задание — show:

$ act --job 'show'

Граф

Опция --graph отображает структуру доступных заданий рабочего процесса в терминале в схематическом виде.

$ act --graph

Вывод команды выглядит следующим образом:

$ act --graph
 ╭─────╮ ╭──────────────╮ ╭───────────────────╮ ╭──────╮
 │ zip │ │ request_test │ │ pull_request_test │ │ show │
 ╰─────╯ ╰──────────────╯ ╰───────────────────╯ ╰──────╯

Переменные окружения

Использовать переменные окружения в act очень просто. Вам нужно только создать новый файл .env. Окружение, доступное в файле .env, act загружает автоматически. Например, мы добавляем переменную ENV_ID.

# .env

ENV_ID='My Env'

Чтобы использовать переменные окружения ENV_ID, используйте синтаксис ${{ env.ENV_ID }} в вашем GitHub action:

# .github/workflows/test.yml

name: Convert files into Zip folder

on: pull_request

jobs:
  show:
    runs-on: ubuntu-latest
    steps:
      - name: Show Env
        run: echo "Env ${{ env.ENV_ID }}"

С помощью опции --env-file можно изменить дефолтное имя файла .env на my-custom.env.

$ act --env-file=my-custom.env

Секреты

Чтобы загружать секреты окружения с помощью act, нужно создать новый файл .secrets. При этом секреты окружения, доступные в файле secrets, загружаются автоматически. Например, мы добавляем переменные APP_SECRET и APP_ID.

APP_SECRET='7824jurd789gyu45esxgfgf48822166974gtredsyujn'
APP_ID='7878974561587'

Чтобы использовать переменные окружения APP_SECRET, используйте синтаксис ${{ secrets.APP_SECRE}} в вашем GitHub action:

# .github/workflows/test.yml

name: Learn environment secrets 

on: pull_request

jobs:
  show:
    runs-on: ubuntu-latest
    steps:
      - name: Show env
        run: echo "App SECRET ${{ secrets.APP_SECRET }}"
      - name: Show varibale
        run: echo "App ID ${{ secrets.APP_ID }}"

Вы можете загрузить свой собственный файл my-custom.secrets, содержащий все ваши секреты, с помощью опции --secret-file.

$ act --secret-file=my-custom.secrets

Заключение

Инструмент командной строки act помогает сэкономить время и силы при локальной работе с GitHub. На данный момент нет другого инструмента, который позволял бы запускать GitHub actions локально.

Но и act не полностью совместим с GitHub actions. Некоторые функции не реализованы, например, параллелизм, нет контекста vars, контекст github неполон и так далее.

Перевод статьи «How to Run GitHub Actions Locally Using the act CLI Tool».

Оставьте комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *

Прокрутить вверх