GitHub Actionsをローカル実行するact｜導入とイメージ選択・再現できる範囲

ワークフローの1行を直すたびにコミットしてpushし、結果を数分待つ。この往復を手元で潰すのがactです。ローカルのDockerでジョブを起動し、ステップの実行順や条件分岐、シェルスクリプトの中身までその場で確かめられます。ただし本物のランナーと同じではありません。この記事では、導入手段の選び方、初回に選ぶイメージ3種の実容量、イベントのpayloadとシークレットの渡し方、そして公式が非対応と明記した機能まで踏み込みます。ワークフローの基本構造はGitHub Actionsとは？できること・使い方とCI/CD自動化の解説記事、パイプライン全体の考え方はCI/CDとは？仕組み・パイプライン・導入すべき企業の判断基準で押さえてください。

まとめ：actで先に決める3つの判断

ひとつ目は、イメージのサイズです。初回起動時に Large・Medium・Micro から選ばされ、選択結果は設定ファイルに書き込まれます。Large はダウンロードだけで約17GB、展開後のストレージは53.1GBに達し、公式は空き75GBを求めます。Medium は500MB前後、Micro は200MB未満。既定値は Medium で、まずはここから始めて足りないツールが出たときだけ個別に足すのが手戻りの少ない順序でした。

ふたつ目は、検証したい対象がactの守備範囲かどうかです。シェルスクリプト、条件分岐、ステップの並び、依存インストール、テスト実行までは手元で再現できます。一方でOIDCによるクラウド認証、環境（environment）に紐づくシークレット、承認ゲート、job.permissionsによる権限縮退は公式が非対応と明記しており、ここを手元で確かめようとすると時間を溶かします。

3つ目は、本番CIとの役割分担です。actは本番CIの置き換えではなく、pushする前のふるいとして置きます。書く前の構文検査をactionlintによるワークフローの静的解析に任せ、書いた後の挙動確認をactに任せ、最終的な合否判定はGitHub上のランナーに戻す。この3段構えなら、ローカルで再現できない領域を無理に追いかけずに済みます。

actの実行モデル｜Docker前提とローカル作業ツリーの扱い

「手元では通ったのにGitHubで落ちる」を避けるため、まず実行モデルを押さえます。

pushせずに回せる検証範囲と実際に起動するコンテナの構成の話

actはカレントディレクトリのワークフロー定義を読み、ジョブごとにDockerコンテナを起動して、ステップを順に流し込みます。JavaScript製のアクションはコンテナ内のNode.jsで、run:のシェルはコンテナのシェルで実行されます。GitHubのランナーVMと違い、1ジョブ＝1コンテナで、ジョブ間のファイル共有は自動では行われません。

コンテナのネットワークは既定でhostです（--networkで変更）。手元のPostgreSQLやモックサーバへlocalhostで届いてしまうため、GitHub上では届かない接続が通ってしまう場合があります。ローカルで通ったテストが本番CIで接続エラーになるときは、まずここを疑ってください。

既定でチェックアウトを飛ばす挙動と未コミット差分がそのまま走る前提

actは既定でチェックアウト用の公式アクションを実際には走らせず、ローカルの作業ディレクトリをコンテナへコピーして代替します。ソースの該当フラグは--no-skip-checkoutで、説明文は「Use actions/checkout instead of copying local files into container」。つまり既定はコピー方式です。

ここから2つの帰結が出ます。第一に、コミットしていない編集中のファイルがそのまま実行対象になります。手元の実験用の設定が混ざったまま「通った」と判断してしまう事故が起きやすい。第二に、fetch-depthやサブモジュール、タグ取得といったチェックアウトの入力値の検証はできません。浅いクローンで壊れる類の問題を確かめたいなら--no-skip-checkoutを付けて本物のチェックアウトを走らせます。

Docker Engine前提とpodmanでの非保証・M系チップの注意

actはDocker Engine APIに依存します。公式は podman など他のコンテナバックエンドについて「it might work, but it is not guaranteed」と書いており、動く保証はありません。Docker Desktop を入れない方針の環境では、ここが最初の関門になります。

Apple の M系チップでは、アーキテクチャを明示しないと警告が出ます。ソースの警告文は「you have not specified container architecture, you might encounter issues」で、対処として--container-architecture linux/amd64が案内されます。amd64のイメージをエミュレーションで動かすぶん遅くなるので、arm64で動くイメージを-Pで割り当てられるならそちらが速く済みました。

インストール手段とイメージ選択｜3種のサイズと必要ディスク容量

迷う点は2つ。どの経路で入れるか、どのイメージを既定にするか。後者のほうが後々効きます。

パッケージ管理・gh拡張・スクリプトでの導入手順と選び方の基準

公式が案内する導入経路は幅広く、環境に合わせて選べます。

• macOS：brew install act、またはsudo port install act
• Windows：winget install nektos.act、choco install act-cli、scoop install act
• Linux：pacman -Syu act、nix-env -iA nixpkgs.act、COPR経由のdnf install act-cli
• GitHub CLI拡張：gh extension installでgh-actを入れ、gh act pushのように呼ぶ
• スクリプト導入：公式のinstall.shをパイプで実行（管理者権限が要る）
• ソースビルド：Go 1.18以上

GitHub CLIを前提にしているプロジェクトなら gh 拡張が扱いやすい。認証済みのghからトークンを渡す流れにそのまま乗るからです。それ以外はOS標準のパッケージ管理で足ります。

Large・Medium・Microの3種と必要ディスク容量の実数

初回実行時、actは既定イメージを選ぶプロンプトを出します。選んだ結果は設定ファイルへ-P行として保存され、次回以降は聞かれません。プロンプトに書かれている実数は次のとおりです。

Large は公式のプロンプトが「空き75GBが要る」と明記するほどで、ノートPCで常用する選択ではありません。Micro はNode.jsだけを含むため、aptやgitを前提にしたステップで即座に落ちます。既定のMediumで走らせ、足りないツールは-Pで自前イメージへ差し替えて補うほうが総容量を抑えられました。

ランナーラベルへのイメージ割り当てと設定ファイルへの固定手順

ランナーラベルとイメージの対応は-Pで指定する仕組みです。書式は-P ラベル=イメージで、複数並べればubuntu-22.04とubuntu-latestを別イメージに割り当てられます。コンテナを使わずホスト側でそのまま走らせたいときは-P ubuntu-latest=-self-hostedという指定になります。WindowsやmacOSのランナーは、この自己ホスト指定でホストOS上を直接使う以外に再現手段がありません。

毎回の指定を避けるには設定ファイル.actrcへ1行1引数で書きます。読み込み順は XDG準拠の場所、ホームディレクトリ、コマンドを叩いたディレクトリ、最後にCLI引数で、後から読まれたものが優先されます。プロジェクト固有の割り当てはリポジトリ直下の.actrcへ置き、個人の好みはホーム側へ置くと衝突しません。コメント行は書けない仕様なので、メモはREADMEへ逃がします。

実行対象の絞り込みとイベントpayload・シークレットの渡し方

actは引数を付けずに叩くとpushイベント相当で全ジョブを流します。実務ではまず対象を絞り、次に値を渡す。この順序で組み立てます。

ジョブ単位・ワークフロー単位で実行対象を絞る指定の書き方と順序

手順としては次の流れが速い。

1. act --listで、検出されたワークフローとジョブの一覧を確認する
2. act -Wでワークフローファイルを1本に絞る
3. act -jでジョブ名を指定し、対象をひとつに落とす
4. act --dryrunで実行せずに流れだけ確かめる
5. マトリックスは--matrixで特定のセルだけへ絞る

依存関係のあるジョブを-jで指定すると、必要な前段ジョブも実行対象に含まれる仕様です。全体像を把握したいときは--graphでジョブの依存を図示でき、他ツールへ食わせるなら--jsonという選択肢もあります。イベント種別を明示したい場合はact pull_requestのように第1引数へ書きます。

イベントのpayloadを実データで流し込む手順と抜けやすい値

ワークフローがgithub.eventの中身を参照している場合、既定の空に近いpayloadでは分岐が期待どおりに動きません。ここで--eventpath（短縮形-e）にJSONファイルを渡します。実際のPRイベントのJSONは、GitHubのAPIやWebhookの配信履歴から取得したものをそのまま保存して使えます。

抜けやすいのはpull_requestイベントでしか定義されない値です。github.head_refのようにイベント依存の値を参照している箇所は、payloadを渡さないまま空文字として評価され、条件式が意図と逆に倒れる挙動です。空文字がどう評価されるかという型キャストの規則はGitHub Actionsの条件分岐（if）｜書く場所で変わるコンテキストと評価の規則で扱っています。どのイベントでどの値が来るかの設計はトリガー（on）のイベント選定とフィルタ設計で整理しています。手動実行用の入力値は--inputと--input-fileで渡せます。

シークレットと変数・入力値の渡し方とトークンの安全な入力方法

値の渡し口は種類ごとに分かれる設計です。シークレットは-s KEY=value、変数（varsコンテキスト）は--var KEY=value、環境変数は--env-fileで、それぞれファイル版の--secret-file・--var-fileも用意されています。ファイル形式はdotenv互換で、改行を含む値もエスケープすれば書けます。

GITHUB_TOKENはactが自動で発行しません。公式は個人アクセストークンを作って渡すか、GitHub CLIを入れているならgh auth tokenの出力を-sへ渡す形を案内しています。ただしこの書き方はシェル履歴に残るため、公式も注意を添えています。値を書かず-s GITHUB_TOKENとだけ書けば対話入力になり、履歴に残りません。シークレットをファイルへ書く場合は、そのファイルをバージョン管理の対象外にしておきます。置き場所そのものの設計と漏えい経路はSecrets管理の置き場所選定と漏えい経路の解説、envとvarsの使い分けは環境変数の使い分けと受け渡しの記事で扱っています。

再現できる機能と落ちる機能の線引き｜公式が非対応と明記した範囲

「actではキャッシュもサービスも動かない」という説明を見かけますが、2026年8月時点のソースを読むと事実と食い違います。実際の線引きを引き直します。

内蔵キャッシュサーバとアーティファクトサーバの起動条件の違い

キャッシュとアーティファクトは、既定の扱いが正反対です。キャッシュサーバは既定で動きます。無効化フラグ--no-cache-serverが存在すること自体が、既定で有効である証拠です。保存先は--cache-server-pathで指定でき、既定はローカルのキャッシュディレクトリ配下、待ち受けポートは--cache-server-portの既定値0で空きポートが自動割り当てされます。

対してアーティファクトサーバは、--artifact-server-pathを渡したときだけ起動する仕様です。フラグの説明にも「If not specified the artifact server will not start.」とあり、指定しなければアップロード系のステップが失敗します。指定するとポート34567で待ち受け、コンテナへACTIONS_RUNTIME_URLなどの環境変数が注入されます。本番側でのアップロードとダウンロードの挙動は、GitHub Actionsのアーティファクト｜受け渡しの設計と同名不可・保持期間の決め方と突き合わせて確認してください。

注意点はひとつ。ローカルのキャッシュはGitHub側のキャッシュとは別物で、共有もされません。手元で復元できたからといって本番CIでヒットする保証はなく、キーの設計ミスは本番でしか露見しません。キーの組み立て方はactions/cacheのkey設計と復元されない原因の切り分けを先に読んでおくと、ローカルとの差分を切り分けやすくなります。

サービスコンテナの起動判定とヘルスチェック未定義時の落とし穴

services:も動作対象です。ジョブにサービス定義があると、actは専用のDockerネットワークを作り、サービスIDをネットワークエイリアスとしてコンテナを起動します。ポート指定も解釈され、ジョブ本体からはサービスID名で接続できます。

問題は起動待ちの判定です。actはコンテナのヘルス状態を最大31回ポーリングし、間隔は1秒から倍々で最大10秒、全体で5分のタイムアウトを持つ実装です。ヘルスが不健全で確定するとservice container failed to startで落ちます。ところがヘルスチェックが定義されていないイメージでは、実装が即座に健全という判定を返します。つまり待ちません。PostgreSQLやRedisをヘルスチェックの指定なしで書いていると、DBが接続を受け付ける前に次のステップが走り、接続拒否でテストが落ちます。ローカルだけ不安定に見えるときの典型がこれでした。

公式が非対応と明記した機能の一覧とローカル検証範囲の見極め方

公式ドキュメントが「無視される」「実装されていない」と明記している機能は、手元で確かめようとするだけ無駄になります。主なものを挙げます。

この表の裏返しが、actで確かめる価値のある領域です。ステップの並びと条件分岐、シェルの中身、依存解決とビルド、テストの通過可否、そしてアクションの入力値の綴り。逆に権限とデプロイ認証まわりは、設計としてGITHUB_TOKENの既定権限と最小権限の設計で詰め、実際の効き目はGitHub上で確認します。

actを常用する条件と見送る場面｜本番CIの代替にしない線引き

ここは条件を付けて言い切ります。全チームに勧める道具ではありません。

常用してよいチームの3条件と回収できる待ち時間の見積もり基準

3つが揃うなら入れる価値があります。第一に、開発者のマシンにDockerがすでに動いていること。第二に、ワークフローを月に何度も触ること。第三に、ジョブの中身がシェルと言語ランタイム中心で、クラウド認証を伴わないこと。

回収できる時間は単純な計算で出ます。ワークフローを直してpushし、キューを待ち、結果を見るまでの1往復が5分だとして、修正が10往復必要な作業なら50分。手元なら初回のイメージ取得を除けば1往復が数十秒に縮みます。逆にワークフローを年に数回しか触らないなら、Mediumイメージの500MB前後の容量とフラグの学習コストのほうが上回りました。この判断を含めてCIの手直しループごと引き取ってほしい場合は、保守運用・内製化支援で開発体制の設計から相談を受けています。

見送る場面の条件｜OIDC前提のデプロイ検証と大容量イメージ

次の場面では入れません。デプロイジョブがOIDCでAWSやGCPの認証を取る構成なら、その核心部分はactで再現できないため、手元で通っても意味を持ちません。承認ゲートや環境別シークレットを検証したい場合も同様に対象外です。macOSランナーやWindowsランナーが必要なビルドも、ホスト実行に切り替えない限り再現できません。

ディスクの制約も現実的な理由のひとつです。ランナー同等の環境を求めてLargeを選ぶと、公式の案内どおり75GBの空きが要ります。開発機の残り容量が数十GBなら、本番CI側で確かめるほうが速く済みます。

静的検査との併用順序と本番CI側で二重化するときの判断の基準

順序を固定します。書いたら静的検査、通ったらact、最後にGitHub。構文ミスや存在しないキー、式の綴り誤りは静的解析が数秒で見つけるので、コンテナを起動して待つ前に潰します。actionlintの導入と使い方をコミット前のフックに入れておけば、actを起動する回数自体が減りました。

本番CI側では、actで確認済みの領域を省略しないでください。ローカルのDockerバージョン、ネットワーク既定値のhost、コピー方式のチェックアウトという3つの差分がある以上、手元の合格は参考値です。actは失敗を早く見つけるための道具で、合格を宣言する道具ではありません。この線を引いておくと、「actで通ったのに」という報告に振り回されずに済みます。

よくある質問

導入時に問い合わせの多い点を、公式ドキュメントとソースの記述に沿ってまとめます。

actの最新バージョンはどれですか？

2026年8月25日時点でGitHubのリリース情報を確認したところ、最新は0.2系の v0.2.89 で、公開日は2026年6月1日でした。直前の v0.2.88 が2026年5月1日、v0.2.87 が2026年4月1日と、毎月1日前後に版が上がる流れが続いています。依存ライブラリの更新が中心の版もあるため、動作に問題がなければ毎回追いかける必要はありません。導入済みの版はact --versionで確認できます。

Dockerなしでactを使えますか？

コンテナを使わない実行は可能ですが、Docker Engine APIへの依存は残る仕様です。-P ubuntu-latest=-self-hostedのようにホスト実行を指定すると、コンテナを起動せずにホストOS上でステップが走ります。この場合、ホストに入っているツールやバージョンがそのまま使われるため、GitHubのランナーとの差はむしろ広がります。podman などの代替バックエンドは公式が動作を保証していません。

actでキャッシュ機能は動きますか？

動きます。actはキャッシュサーバを内蔵しており、既定で有効です（無効化は--no-cache-server）。保存先は--cache-server-pathで変更できます。ただしローカルに保存されるだけで、GitHub側のキャッシュとは共有されません。キーが本番でヒットするかどうかは手元では判定できないため、キー設計の妥当性はGitHub上の実行ログで確かめてください。

ローカルでは成功するのにGitHubで失敗するのはなぜですか？

差分が出やすいのは4点です。既定でチェックアウトを飛ばすため未コミットの変更が走っていること、ネットワークが既定でhostのため手元のサービスへ届いてしまうこと、イメージにランナー同等のツールが入っていないこと、そしてpermissionsやtimeout-minutesのような無視される設定があることです。まず--no-skip-checkoutを付け、クリーンな状態で再実行して切り分けます。

CI環境をactに置き換えてもよいですか？

置き換えは勧めません。OIDC認証、環境保護ルール、同時実行制御、注釈といったGitHub側の機能が無視されるため、合否判定の根拠になりません。pushする前の手戻り削減に用途を限定し、最終判定はGitHub上のランナーへ残す構成にしてください。ローカルとCIで実行内容を揃えたいなら、テスト実行をスクリプトやタスクランナーへ切り出し、両方から同じスクリプトを呼ぶ形が扱いやすくなります。

関連記事

• actionlintとは？GitHub Actionsのワークフローを静的解析するLintツールの導入・使い方：actを起動する前に構文と式の誤りを潰す工程です。
• GitHub ActionsのSecrets管理｜置き場所の選定と漏えい経路・OIDC移行の判断：手元へ渡す値の本来の置き場所を設計できます。
• GitHub Actionsのキャッシュ｜actions/cacheのkey設計と復元されない原因の切り分け：ローカルのキャッシュと本番の差を切り分けられます。
• GitHub Actionsのトリガー（on）｜イベント選定とbranches・pathsフィルタの設計：渡すpayloadの中身を決める前提になります。
• GitHub Actionsの環境変数｜env・vars・secretsの使い分けと受け渡し：変数と環境変数で渡す値の設計に対応します。