ローカルでGitHub Actionsをシミュレート！「act」を使ってCI/CDフィードバックループを爆速化する
「コードを修正する $\rightarrow$ `git push` $\rightarrow$ GitHub Actionsが走る $\rightarrow$ 失敗 $\rightarrow$ 軽微なタイポを修正 $\rightarrow$ 再び `git push`」
この絶望的なまでの「待ち時間」に、あなたの開発リソースと精神力はどれだけ削られてきただろうか？
CIが完了するまでの数分間、コーヒーを飲みに行く、SNSを見る、そして戻ってきた頃にはフローのコンテキストが完全に切れている――。この「CI待ち地獄」は、モダンな開発チームの生産性を静かに蝕む最大級のガンだ。
こんにちは。日々、極限まで最適化されたパイプラインを追求するテックリードの私から、今日、その悪夢に終止符を打つための決定的な武器を授けよう。
オープンソースのツール「act」だ。
今回は、GitHub Actionsのワークフローをあなたのローカルマシン上で完全にシミュレートし、フィードバックループを亜音速化するための実践的知見を余すところなく伝授する。
—
なぜ `act` なのか？（そしてDockerとの関係）
`act` は、Go言語で書かれたオープンソースのCLIツールであり、GitHub Actionsのワークフロー（`.github/workflows/.yml`）をローカルのDockerコンテナ上で実行する。
「ローカルでテストするなら、シェルスクリプトでよくないか？」と思うかもしれない。だが、それでは意味がない。
`act` は、GitHubが提供する公式のランナー環境（`ubuntu-latest` など）とほぼ同等のDockerイメージ（nektos/act環境など）を使用し、環境変数、シークレット、マトリクスビルド、果てはワークフロー間の依存関係（`needs`）まで完璧にエミュレートする。
つまり、「ローカルで動いたものが、GitHub上で落ちるわけがない」という絶対的な確信を得ながら開発を進められるのだ。
—
1. 導入と環境構築の極意
まずはインストールからだが、単にツールを入れるだけでは不十分だ。本番同等の挙動を得るための「正しいセットアップ」を行う。
インストール (macOS / Linux / Windows)
macOSであればHomebrew一撃だ。
brew install act
LinuxやWindows（WSL2推奨）の場合は、公式リポジトリのスクリプト等を参照してほしい。
必須の前提：Docker Daemonの最適化
`act` は裏でDockerを激しく酷使する。もしあなたのマシンのDockerリソース（CPU/メモリ）がデフォルトのままであれば、今すぐDocker Desktopの設定を開き、以下のように引き上げろ。
- Memory: 最低 4GB（できれば 8GB以上）
- CPU: 最低 4コア以上
これが不足していると、大規模なマトリクスビルドをローカルで回した際にコンテナがフリーズする原因になる。
—
2. 実戦投入：極限まで最適化されたワークフロー設定と実行
ここでは、よくあるテストとビルドを行う実践的なワークフロー（`ci.yml`）を例に取る。
設定ファイル例: `.github/workflows/ci.yml`
name: CI/CD Pipeline
on:
push:
branches: [ main, develop ]
pull_request:
branches: [ main ]
jobs:
test:
runs-name: Node.js Test Runner
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [18.x, 20.x]
steps:
# リポジトリのチェックアウト
- name: Checkout Code
uses: actions/checkout@v4
# Node.js環境のセットアップ
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: ‘npm’
依存関係のインストール
- name: Install Dependencies
run: npm ci
# テストの実行
- name: Run Unit Tests
run: npm test
env:
CI: true
DATABASE_URL: “postgres://test:test@localhost:5432/test_db”
ローカル実行の基本コマンド
このワークフローをローカルで走らせるには、プロジェクトのルートディレクトリで以下のコマンドを叩くだけだ。
act push
これだけで、`.github/workflows/ci.yml` の `push` トリガーにマッチするジョブがローカルのDocker上で立ち上がり、ログがリアルタイムで流れる。
—
3. 開発スピードを爆発させる「プロの実践テクニック」
ここからが本番だ。単に `act` を使うだけでは、真の生産性向上には届かない。プロが現場で使っているハックと設定を公開する。
① イメージサイズと速度のトレードオフを制する（`-P` オプション）
`act` はデフォルトで巨大なフルサイズのDockerイメージ（`ubuntu-latest` 相当の数GBあるイメージ）を使おうとするため、初回ダウンロードやコンテナ起動に時間がかかる。
爆速のフィードバックを得るために、軽量なイメージ（Medium / Micro）を明示的に指定せよ。`.actrc` という設定ファイルをプロジェクトのルートに配置するのが定跡だ。
推奨 `.actrc` 設定ファイル
.actrc
デフォルトの巨大イメージの代わりに、軽量なイメージをマッピングする
-P ubuntu-latest=catthehacker/ubuntu:act-latest
-P ubuntu-22.04=catthehacker/ubuntu:act-22.04
-P ubuntu-20.04=catthehacker/ubuntu:act-20.04
カラー出力を有効化
–container-architecture linux/amd64
※ `catthehacker/ubuntu` シリーズは、GitHub Actions公式ランナーのツール群（Node, Git, Dockerなど）が予め入っており、actユーザーの間ではデファクトスタンダードとして使われている神イメージだ。
② シークレットと環境変数の安全なローカル管理
APIキーやデータベースの認証情報など、CIで必須となるシークレットをどう扱うか？
本物の機密情報をハードコードするのは御法度だ。`.env` ファイルを作成し、`act` に読み込ませる。
1. ルートに `.secrets` ファイルを作成：
STRIPE_API_KEY=sk_test_dummy12345
AWS_ACCESS_KEY_ID=dummy_access_key
2. 実行時に渡す：
act –secret-file .secrets
これで、ワークフロー内の `secrets.STRIPE_API_KEY` が安全にモックされる。
③ 特定のジョブだけをピンポイントでデバッグする
マトリクスビルド全体を回すと時間がかかる場合、あるいは特定のジョブ（例: `test` ジョブの Node 20.x だけ）をデバッグしたい場合は、`-j` オプションを使え。
act -j test –matrix node-version:20.x
これにより、無駄な待ち時間を完全に排除し、数秒単位のイテレーションが可能になる。
—
4. トラブルシューティング：ローカル特有の「ハマりどころ」
最後に、`act` を導入したエンジニアが必ず直面する「罠」と、その回避策を共有しておく。
- Q. Dockerソケット（`var/run/docker.sock`）にアクセスするジョブ（Docker in Docker系）が失敗する
- A: `act` 自体がDocker内でコンテナを立ち上げる構造上、そのままではDind（Docker in Docker）は動かない。ホストのDockerソケットを共有させるため、実行時に `-v /var/run/docker.sock:/var/run/docker.sock` を付与するか、セキュリティ上の理由から、ローカルシミュレーションではDockerビルドステップをスキップするように環境変数を調整せよ。
- Q. キャッシュが効かなくて毎回重い
- A: `actions/cache` はローカル環境では動きづらい。`act` は `–reuse-containers` フラグをサポートしており、これを使うと前回のコンテナ状態を維持したまま再実行できるため、ビルドの体感速度が劇的に向上する。
act push –reuse-containers
—
結び：CIは「祈るもの」ではなく「ローカルで確信するもの」だ
多くの開発現場において、CI/CDパイプラインは「コードを放り込んで、うまく行くことを祈るブラックボックス」になりがちだ。
しかし、`act` を導入したチームの文化は違う。彼らはローカルで完全にテストをパスさせてからプッシュするため、GitHub上のCIは単なる「最終確認の儀式」に変貌する。プッシュボタンを押した瞬間に緑色のチェックマーク（`1 passed`）が並ぶ快感を、ぜひあなたのチームでも味わってほしい。
さあ、今すぐ `brew install act` を叩き、CI待ちの呪縛から解放された真の爆速開発フローを手に入れろ。