ActでGitHub Actionsをローカルで実行
actを使用してGitHub Actionsをローカルマシンで実行する方法を学び、時間を節約し開発効率を向上させましょう。
ワークフローが期待通り動作しないとき、GitHubにコードをプッシュしてテストしたことはありますか?それとも、小さな変更のたびにCIが再実行されるのを数分待ったことがありますか?🤔
この記事では、act - GitHubのサーバーでリモート処理を待つのではなく、ローカルマシンでGitHub Actionsを直接実行できるツールを紹介します。
なぜGitHub Actionsをローカルで実行するのか?#
CI/CDワークフローを修正しているとします。現在のプロセスは通常次の通りです:
- ワークフローファイルを編集
- コードをコミットしてプッシュ
- GitHub Actionsの実行を待つ(数分かかる場合がある)
- エラーが発生
- ステップ1に戻る
これは、ドキュメントの一文を修正するたびに同僚にメールを送るようなもので、直接編集できないことを意味します。非常に時間がかかり、非効率的です。
actはこの問題を解決します:
- 高速フィードバック - プッシュなしでワークフローを即座に実行
- ローカルタスクランナー - MakefileをGitHub Actionsで置き換え、既存のワークフロー構造を活用
- 依存関係の削減 - アクションとイメージがキャッシュされている場合、インターネット接続が不要
Actはどのように動作しますか?#
GitHub Actionsを工場と考えてください。コードをプッシュすると、GitHubは次のことを行います:
.github/workflows/からワークフローファイルを読み取る- 実行が必要なアクションを決定
- それに応じてDockerイメージをプルまたはビルド
- 各アクションをコンテナで実行
- GitHubと一致するように環境変数とファイルシステムを設定
actはGitHubのサーバーではなく、あなたのマシンで全く同じことを行います:
Actのインストール#
前提条件#
actはワークフローをコンテナで実行するためにDockerが必要です。コンテナ分離が必要ない場合(例:windows/macOSジョブをマシンで直接実行)、Dockerをスキップできます。
- macOS: Docker Desktop for Macをインストール
- Windows: Docker Desktop for Windowsをインストール
- Linux: Docker Engineをインストール
クイックインストール#
方法1: Homebrew(macOS & Linux)
brew install actbash方法2: Bashスクリプト(全プラットフォーム)
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bashbash方法3: GitHub CLI拡張機能
gh extension install https://github.com/nektos/gh-actbash方法4: 直接ダウンロード
GitHub releases ↗からダウンロードしてPATHに追加。
[!TIP] インストールを確認:
bashact --version
Actの基本的な使用法#
デフォルトワークフローを実行#
デフォルトでは、actはイベントpushですべてのワークフローを実行します:
actbash特定のイベントで実行#
act pull_request
act schedule
act workflow_dispatchbashワークフローを一覧表示#
act -l pull_requestbash特定のワークフローを実行#
act -W .github/workflows/checks.ymlbash特定のジョブを実行#
act -j testbashシークレットと変数の設定#
シークレットの使用#
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 .secretsbash[!WARNING] ターミナルで機密データを入力すると、シェル履歴に保存される可能性があります。セキュリティのため、方法2または3を使用してください。
リポジトリ変数の使用#
act --var VARIABLE=some-value
act --var-file .envbash.envファイル形式#
Ruby dotenv形式と一致:
MY_ENV='value'
PRIV_KEY="---...\nrandom text\n...---"
JSON="{\n\"name\": \"value\"\n}"
SOME_VAR=SOME_VALUEbashローカル実行時のジョブとステップのスキップ#
ジョブをスキップ#
カスタムイベントプロパティを使用:
on: push
jobs:
deploy:
if: ${{ !github.event.act }} # ローカル実行時にスキップ
runs-on: ubuntu-latest
steps:
- run: echo "Deploy step"yamlevent.jsonを作成:
{
"act": true
}json実行:
act -e event.jsonbashステップをスキップ#
actは環境変数ACTを提供します:
- name: Notify Slack
if: ${{ !env.ACT }} # ローカル実行時にスキップ
run: |
curl -X POST $SLACK_WEBHOOKyamlマトリックスと高度な機能#
マトリックスのサブセットを実行#
ワークフローに複数の値を持つマトリックスがある場合:
strategy:
matrix:
node: [14, 16, 18]
os: [ubuntu-latest, macos-latest]yamlnode 18のみで実行:
act push --matrix node:18bashnode 18とubuntuのみで実行:
act push --matrix node:18 --matrix os:ubuntu-latestbashアクションオフラインモード#
キャッシュ時に高速化してオフラインで実行:
act --action-offline-modebashメリット:
- 既存のイメージをプルしない
- キャッシュされている場合オフラインで動作
- GitHubのレート制限を回避
- 接続が悪い場合に時間を節約
.actrc設定ファイル#
毎回フラグを入力しないように、.actrcを作成:
--container-architecture=linux/amd64
--action-offline-mode
-e event.jsonbash問題と制限#
Apple Silicon(M1/M2/M3)#
Apple Mシリーズチップを使用している場合、アーキテクチャの問題が発生する可能性があります:
act --container-architecture linux/amd64bashランナーイメージ#
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固有の機能
実用的な例#
シンプルなワークフロー#
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 testyamlローカルで実行:
actbashシークレットを使用するワークフロー#
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_URLbashGitHub Actionsとの比較#
| 機能 | GitHub Actions | act(ローカル) |
|---|---|---|
| フィードバック速度 | 遅い(プッシュが必要) | 高速(即座実行) |
| リソースコスト | GitHubアカウントクォータ | ローカルマシン |
| 環境 | 正確 | ほぼ正確 |
| オフライン | 不可 | 可能(オフラインモードで) |
| マトリックステスト | 時間がかかる | 高速(サブセット実行) |
| シークレット | GitHubで管理 | 手動渡し |
結論#
actはGitHub Actionsを使用する開発者にとって不可欠なツールです。以下の助けになります:
- 開発とワークフローデバッグの高速化
- GitHubインフラストラクチャへの依存削減
- プッシュ前のワークフローテスト
- ローカルタスクランナーとしてのGitHub Actions活用
[!TIP] ベストプラクティス:特に複雑なワークフロー構造を変更する場合、プッシュ前に必ずactでワークフローをテストしてください。