Act とは？

Act は、ローカル環境で GitHub Actions Workflow を実行できるオープンソースの CLI ツールです。コードを GitHub にプッシュしなくても、CI/CD パイプラインのテストとデバッグが可能です。

GitHub Actions を頻繁に書く開発者にとって、これは効率化の神器と言えます。

  • 高速なイテレーション：workflow を修正後、すぐにローカルで実行できます。GitHub のキュー待ちや実行時間を待つ必要がありません。
  • リソース節約：GitHub Actions の消費分（特にプライベートリポジトリ）を節約できます。
  • オフラインデバッグ：ネットワーク接続がない環境でも workflow をテストできます。
  • 安全なテスト：隔離された環境で workflow の安全性を検証でき、危険な操作が誤って実行されるのを防げます。

なぜ Act が必要なのか？

GitHub Actions は強力な CI/CD プラットフォームですが、workflow のデバッグには痛点があります。

.github/workflows/test.yml を修正
→ git commit
→ git push
→ GitHub のキュー待ち（数分〜数時間かかることも）
→ ログを確認してエラー発見
→ 上記を繰り返す

このサイクルは非常に時間がかかります。Act を使えば、こうなります。

.github/workflows/test.yml を修正
→ act -j test    # ローカルで即座に実行
→ 出力を確認して問題を修正
→ 再度実行して確認无误后再推送

効率は少なくとも 10 倍向上します。

Act vs 他のソリューション

機能 Act GitHub Web UI Docker Compose シミュレーション
実行速度 ⚡ ローカル即時 🐌 キュー待ち必要 ⚡ ローカルだが設定複雑
信頼性 ✅ 本物の GitHub Actions runner イメージを使用 ✅ 完全に本物 ❌ 手動シミュレーション必要
コスト 💰 無料（ローカル実行） 💰 Actions 分数を消費 💰 無料
使いやすさ ✅ 1コマンド ✅ GUI ❌ 設定が煩雑
オフライン対応 ✅ 完全オフライン可能 ❌ ネットワーク必要 ✅ オフライン可能

Act のインストール

macOS（Homebrew）

BASH 
brew install act

Linux

Ubuntu/Debian：

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

Arch Linux：

BASH 
yay -S act
# または
paru -S act

Windows

Chocolatey：

POWERSHELL 
choco install act-cli

Scoop：

POWERSHELL 
scoop install act

インストール確認

BASH 
act --version
# 出力例：act version 0.2.x

クイックスタート：最初の Workflow を実行

前提条件

プロジェクトのルートディレクトリに .github/workflows/ ディレクトリがあり、その中に少なくとも1つの workflow ファイル（.yml または .yaml）があることを確認してください。

利用可能な Workflow を一覧表示

BASH 
cd /path/to/your/project
act -l

出力例：

Stage  Job ID  Job name  Workflow name  Workflow file  Events
0      test    Test      CI             ci.yml         push,pull_request
0      build   Build     CI             ci.yml         push,pull_request

指定した Job を実行

BASH 
# test という名前の job を実行
act -j test

# すべての job を実行
act

# 特定のイベントでトリガーされる workflow を実行（例：pull_request）
act pull_request

初回実行時の注意点

初回実行時、Act は必要な Docker イメージ（通常は catthehacker/ubuntu:act-latest）をダウンロードします。これには数分かかる場合があります。次回以降の実行ではキャッシュが使用され、より高速になります。

INFO[0000] Using docker host 'unix:///var/run/docker.sock'
INFO[0000] Pulling image 'catthehacker/ubuntu:act-latest'
...

応用テクニック

1. 異なる Runner イメージを使用

Act はデフォルトで Ubuntu イメージを使用しますが、-P パラメータで異なるプラットフォームを指定できます。

BASH 
# Ubuntu 22.04 を使用
act -P ubuntu-latest=catthehacker/ubuntu:act-22.04

# Ubuntu 20.04 を使用
act -P ubuntu-latest=catthehacker/ubuntu:act-20.04

# 軽量イメージを使用（高速だが機能制限あり）
act -P ubuntu-latest=node:16-buster-slim

2. Secret と環境変数を渡す

多くの workflow は secret（API キー、Token など）に依存しています。.env ファイルまたはコマンドラインで渡せます。

方法1：.env ファイルを使用

プロジェクトのルートディレクトリに .env ファイルを作成します。

BASH 
MY_API_KEY=your_secret_key
GITHUB_TOKEN=ghp_xxxxxxxxxxxx

その後、実行します。

BASH 
act --secret-file .env

方法2：コマンドラインで直接渡す

BASH 
act -s MY_API_KEY=your_secret_key -s GITHUB_TOKEN=ghp_xxxxxxxxxxxx

3. 複数の Job を並列実行

workflow に独立した複数の job がある場合、--parallel で高速化できます。

BASH 
act --parallel

4. ドライランモード（Dry Run）

実際に実行せず、実行予定のステップのみを表示します。

BASH 
act -n

5. カスタム作業ディレクトリ

workflow が特定のディレクトリ構造に依存している場合、バインドマウントできます。

BASH 
act --bind

これにより、現在のディレクトリがコンテナ内にマウントされ、ファイルの変更がリアルタイムで反映されます。

実践ケース

ケース1：Node.js プロジェクトの CI をデバッグ

Node.js プロジェクトがあり、workflow が以下のようだと仮定します。

YAML 
# .github/workflows/nodejs.yml
name: Node.js CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

ローカルで実行します。

BASH 
act -j test

テストが失敗した場合、Act は完全なログ出力を表示するので、問題の特定が容易です。

ケース2：複数バージョンの Python マトリックスをテスト

YAML 
# .github/workflows/python.yml
name: Python Tests

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.9', '3.10', '3.11', '3.12']

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Run tests
        run: pytest

すべての Python バージョンのテストを実行します。

BASH 
act -j test

Act は自動的にマトリックス内のすべての組み合わせを順次実行します。

ケース3：Docker ビルドをデバッグ

YAML 
# .github/workflows/docker.yml
name: Build Docker Image

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build Docker image
        run: docker build -t myapp:${{ github.sha }} .

      - name: Run tests in container
        run: docker run myapp:${{ github.sha }} npm test

ローカルで実行する前に、Docker デーモンが起動していることを確認してください。

BASH 
# Docker が利用可能か確認
docker info

# workflow を実行
act -j build

よくある問題のトラブルシューティング

問題1：権限エラー

現象： permission denied while trying to connect to the Docker daemon socket

解決策：

BASH 
# 現在のユーザーを docker グループに追加
sudo usermod -aG docker $USER
# 再ログインするか、newgrp docker を実行

または sudo で Act を実行します（非推奨）。

BASH 
sudo act

問題2：メモリ不足

現象： 大規模な workflow 実行時に OOM（Out of Memory）が発生

解決策： 同時実行する job 数を制限します。

BASH 
act --max-parallel 1

問題3：Action が見つからない

現象： unable to find action 'actions/checkout@v4'

解決策： Act は GitHub から action をダウンロードする必要があります。ネットワーク接続が正常であることを確認してください。プライベート action の場合は、GITHUB_TOKEN を設定する必要があります。

問題4：環境変数が有効にならない

現象： workflow で参照される環境変数が空

解決策： --secret-file または -s で変数が正しく渡されていることを確認し、workflow で ${{ env.VAR_NAME }} または ${{ secrets.VAR_NAME }} で参照していることを確認してください。

ベストプラクティス

  1. プッシュ前に常にローカルテスト：workflow を修正したら、まず Act で検証する習慣をつけましょう。
  2. .env ファイルで secret を管理：機密情報をハードコードしないでください。.env を .gitignore に追加しましょう。
  3. Act を定期的に更新：brew upgrade act または最新バージョンを再ダウンロードしてインストールしましょう。
  4. VS Code と組み合わせる：GitHub Actions 拡張機能をインストールし、エディタ内で workflow を直接プレビューしましょう。
  5. CI で Act をオプションステップとして維持：PR テンプレートでコントリビューターにローカルテストを促すことができます。

まとめ

Act は GitHub Actions 開発者の必須ツールです。本来なら数分〜数時間かかるデバッグサイクルを、数秒に短縮できます。シンプルな単体テスト workflow から、複雑な多段階デプロイパイプラインまで、Act でローカルで迅速に検証できます。

主な利点のおさらい： - ⚡ 高速イテレーション：ローカル即時実行、GitHub のキュー待ち不要 - 💰 コスト削減：GitHub Actions 分数を消費しない - 🔒 安全な隔離：コンテナ内で実行され、ホスト環境に影響しない - 🛠️ 本物に近い環境：GitHub と同じ runner イメージを使用し、結果が信頼できる

GitHub Actions workflow を頻繁に作成・保守しているなら、Act をツールボックスに加えることを強くお勧めします。

関連リンク： - Act GitHub リポジトリ - Act 公式ドキュメント - GitHub Actions ドキュメント