blog.dopana

戻る

ワークフローが期待通り動作しないとき、GitHubにコードをプッシュしてテストしたことはありますか?それとも、小さな変更のたびにCIが再実行されるのを数分待ったことがありますか?🤔

この記事では、act - GitHubのサーバーでリモート処理を待つのではなく、ローカルマシンでGitHub Actionsを直接実行できるツールを紹介します。

なぜGitHub Actionsをローカルで実行するのか?#

CI/CDワークフローを修正しているとします。現在のプロセスは通常次の通りです:

  1. ワークフローファイルを編集
  2. コードをコミットしてプッシュ
  3. GitHub Actionsの実行を待つ(数分かかる場合がある)
  4. エラーが発生
  5. ステップ1に戻る

これは、ドキュメントの一文を修正するたびに同僚にメールを送るようなもので、直接編集できないことを意味します。非常に時間がかかり、非効率的です。

actはこの問題を解決します:

  • 高速フィードバック - プッシュなしでワークフローを即座に実行
  • ローカルタスクランナー - MakefileをGitHub Actionsで置き換え、既存のワークフロー構造を活用
  • 依存関係の削減 - アクションとイメージがキャッシュされている場合、インターネット接続が不要

Actはどのように動作しますか?#

GitHub Actionsを工場と考えてください。コードをプッシュすると、GitHubは次のことを行います:

  1. .github/workflows/からワークフローファイルを読み取る
  2. 実行が必要なアクションを決定
  3. それに応じてDockerイメージをプルまたはビルド
  4. 各アクションをコンテナで実行
  5. GitHubと一致するように環境変数とファイルシステムを設定

actはGitHubのサーバーではなく、あなたのマシンで全く同じことを行います:

actを実行ワークフローファイルを読み取り実行するアクションを決定Docker APIイメージをプル/ビルドコンテナを実行環境とファイルシステムを設定ワークフローを実行

Actのインストール#

前提条件#

actはワークフローをコンテナで実行するためにDockerが必要です。コンテナ分離が必要ない場合(例:windows/macOSジョブをマシンで直接実行)、Dockerをスキップできます。

  • macOS: Docker Desktop for Macをインストール
  • Windows: Docker Desktop for Windowsをインストール
  • Linux: Docker Engineをインストール

クイックインストール#

方法1: Homebrew(macOS & Linux)

Homebrew
brew install act
bash

方法2: Bashスクリプト(全プラットフォーム)

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
bash

方法3: GitHub CLI拡張機能

gh extension install https://github.com/nektos/gh-act
bash

方法4: 直接ダウンロード

GitHub releases ↗からダウンロードしてPATHに追加。

[!TIP] インストールを確認:

act --version
bash

Actの基本的な使用法#

デフォルトワークフローを実行#

デフォルトでは、actはイベントpushですべてのワークフローを実行します:

すべてのワークフローを実行
act
bash

特定のイベントで実行#

pull_requestイベントをシミュレート
act pull_request

act schedule

act workflow_dispatch
bash

ワークフローを一覧表示#

pull_requestのワークフローを一覧表示
act -l pull_request
bash

特定のワークフローを実行#

checks.ymlワークフローを実行
act -W .github/workflows/checks.yml
bash

特定のジョブを実行#

testという名前のジョブのみを実行
act -j test
bash

シークレットと変数の設定#

シークレットの使用#

GitHubはサーバーでワークフローを実行するとき、自動的にGITHUB_TOKENを提供します。ローカルで実行する場合、自分で提供する必要があります:

act -s MY_SECRET=my-value

# 方法2: 環境変数を使用(推奨)
act -s MY_SECRET

# 方法3: GitHub CLIからトークンを自動取得
act -s GITHUB_TOKEN="$(gh auth token)"

# 方法4: ファイルから読み込み
act --secret-file .secrets
bash

[!WARNING] ターミナルで機密データを入力すると、シェル履歴に保存される可能性があります。セキュリティのため、方法2または3を使用してください。

リポジトリ変数の使用#

変数を渡す
act --var VARIABLE=some-value

act --var-file .env
bash

.envファイル形式#

Ruby dotenv形式と一致:

MY_ENV='value'
PRIV_KEY="---...\nrandom text\n...---"
JSON="{\n\"name\": \"value\"\n}"
SOME_VAR=SOME_VALUE
bash

ローカル実行時のジョブとステップのスキップ#

ジョブをスキップ#

カスタムイベントプロパティを使用:

workflow.yml
on: push
jobs:
  deploy:
    if: ${{ !github.event.act }} # ローカル実行時にスキップ
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploy step"
yaml

event.jsonを作成:

event.json
{
  "act": true
}
json

実行:

act -e event.json
bash

ステップをスキップ#

actは環境変数ACTを提供します:

workflow.yml
- name: Notify Slack
  if: ${{ !env.ACT }} # ローカル実行時にスキップ
  run: |
    curl -X POST $SLACK_WEBHOOK
yaml

マトリックスと高度な機能#

マトリックスのサブセットを実行#

ワークフローに複数の値を持つマトリックスがある場合:

workflow.yml
strategy:
  matrix:
    node: [14, 16, 18]
    os: [ubuntu-latest, macos-latest]
yaml

node 18のみで実行:

act push --matrix node:18
bash

node 18とubuntuのみで実行:

act push --matrix node:18 --matrix os:ubuntu-latest
bash

アクションオフラインモード#

キャッシュ時に高速化してオフラインで実行:

オフラインモードを有効化
act --action-offline-mode
bash

メリット:

  • 既存のイメージをプルしない
  • キャッシュされている場合オフラインで動作
  • GitHubのレート制限を回避
  • 接続が悪い場合に時間を節約

.actrc設定ファイル#

毎回フラグを入力しないように、.actrcを作成:

.actrc
--container-architecture=linux/amd64
--action-offline-mode
-e event.json
bash

問題と制限#

Apple Silicon(M1/M2/M3)#

Apple Mシリーズチップを使用している場合、アーキテクチャの問題が発生する可能性があります:

act --container-architecture linux/amd64
bash

ランナーイメージ#

actはGitHubランナーとは異なるDockerイメージを使用します。一部のツールが動作しない場合があります:

  • ubuntu-latest → node:16-buster-slim(軽量)またはcatthehacker/ubuntu:act-latest(中程度)
  • GitHubと完全に一致する環境には、nektos/act-environments-ubuntu:18.04を使用

サポートされていない機能#

一部のGitHub Actions機能はサポートされていません:

  • Dockerコンテキスト
  • 一部の複雑なマトリックス設定
  • 一部のGitHub Actions固有の機能

実用的な例#

シンプルなワークフロー#

.github/workflows/test.yml
name: Test
on: push
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '18'
      - name: Install
        run: npm install
      - name: Test
        run: npm test
yaml

ローカルで実行:

act
bash

シークレットを使用するワークフロー#

.github/workflows/deploy.yml
name: Deploy
on: push
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to production
        run: |
          curl -X POST ${{ secrets.DEPLOY_URL }}
yaml

ローカルで実行:

act -s DEPLOY_URL
bash

GitHub Actionsとの比較#

機能GitHub Actionsact(ローカル)
フィードバック速度遅い(プッシュが必要)高速(即座実行)
リソースコストGitHubアカウントクォータローカルマシン
環境正確ほぼ正確
オフライン不可可能(オフラインモードで)
マトリックステスト時間がかかる高速(サブセット実行)
シークレットGitHubで管理手動渡し

結論#

actはGitHub Actionsを使用する開発者にとって不可欠なツールです。以下の助けになります:

  • 開発とワークフローデバッグの高速化
  • GitHubインフラストラクチャへの依存削減
  • プッシュ前のワークフローテスト
  • ローカルタスクランナーとしてのGitHub Actions活用

[!TIP] ベストプラクティス:特に複雑なワークフロー構造を変更する場合、プッシュ前に必ずactでワークフローをテストしてください。

参考文献#