act

act

act は GitHub Actions ワークフローに対する第 2 の防御線であり、 actionlint スキルの後段に位置します。 actionlint は静的なチェックで、ワークフローが構文的に正しく解析され、 式と型が妥当であることを検証します。 act は動的なチェックで、ワークフローを Docker 内でローカル実行し、 実際に動作するかを確認します。

ゲートではなく、提案として使ってください。 ステージングされたワークフローで actionlint のチェックが通ったら、 act で実行して実際の失敗がないか確認することを提案します。 ただし、act を理由にコミットをブロックしてはいけません。 ローカル実行ではすべてを網羅できず、 ローカル環境も不安定です。

迷ったら、オペレーターに確認してください

あいまいな点があれば、 特に、失敗がワークフローに起因するのか、 ローカル環境に起因するのかが不明な場合は、 推測せずにオペレーターに確認してください。 壊れたワークフローを問題ないと判断したり、 ローカルイメージがないだけの失敗をオペレーターに心配させたりするより、 質問するほうが手間はかかりません。 以下のすべての手順で、この方針を適用してください。

実行するタイミング

• ステージングされたワークフローファイルで actionlint のチェックが通った後 — 安価な静的チェックで却下されたワークフローに Docker を使わないでください。
• ワークフローを変更するすべてのコミットで提案してください。 必須ではありません。 実行を提案し、オペレーターが断った場合はスキップしてください — コミットはブロックされません。

前提条件

実行には、正常に動作する Docker と事前設定済みのイメージが必要です。 まず確認してください。いずれかが欠けている場合は、 オペレーターに伝えて実行をスキップし、コミットを続行してください — 前提条件を理由にブロックしてはいけません。

1. Docker に接続できること — docker info が成功すること （Docker Desktop、colima、podman info 経由の podman など、プロバイダーは問いません）。 バイナリがない場合やデーモンが停止している場合、act は実行できません。スキップしてください。
2. デフォルトのランナーイメージが設定されていること。 act は初回実行時にイメージのサイズを対話形式で尋ねます。 TTY がないと fatal EOF で終了するため、事前に設定しておく必要があります。 設定は act の actrc （macOS では ~/.config/act/actrc、~/.actrc、 または ~/Library/Application Support/act/actrc）にあります。 設定済みの場合は、-P のデフォルト行があります。 設定されていない場合は、オペレーターに act を一度実行して Medium （約 500MB。Large は約 70GB、Micro は node のみ）を選ぶよう依頼してください — イメージを推測してはいけません。 実行時に初めて未設定だとわかった場合（fatal EOF が発生した場合）は、そこで停止して確認してください。
3. ホストフラグ。
   • Apple Silicon — 最初から追加します。 uname -m → arm64 の場合 → --container-architecture linux/amd64。
   • デーモンソケットのバインドマウント失敗（colima で発生例あり） — 初回実行で確認された場合に限り、その後で追加します。 --container-daemon-socket -。

手順

1. 最初に、ステージ済みのワークフローが actionlint を通ることを確認します — actionlint スキル、または actionlint の直接実行で確認します。 act は二番手であり、最初ではありません。

2. 実行を提案します — 「ステージ済みのワークフローを act で実行して、実際に動作するか確認しますか？」とオペレーターに一行で尋ねます。 断られた場合 → スキップしてコミットを続行します（act が妨げることはありません）。

3. 上記の前提条件に加えて、act がインストールされていることを確認します（command -v act）。 act がインストールされていない場合は、インストールを別途依頼します — mise.toml を編集するためです（下記参照）。実行の提案ではインストールの許可は得られていません。 前提条件が一つでも満たされていない場合 → オペレーターに伝え、スキップしてコミットを続行します。

4. ステージ済みのワークフローファイルに対して act を実行します — ステージ済みのワークフローファイルごとに -W を指定して実行します。 act が読み込むのはインデックスではなく作業ツリーなので、 まずファイルに未ステージの変更がないことを確認します （git diff -- <file> が空であること）。 変更がある場合は、実行前に再ステージします（git add）。

   mise exec -- act -W .github/workflows/<staged-file> [host-flags]
   

   • act がすでに PATH 上にない場合に限り、mise exec -- を付けます。
   • [host-flags] = 前提条件3に該当するフラグ（アーキテクチャ／ソケット）。
   • act がイベント（push、またはワークフローで唯一のイベント）を選択します。 必要に応じて <event> または -j <job> で絞り込みます。
   • ジョブを事前に絞り込まないでください — 実行できないジョブは環境エラーとして表面化させます（手順5）。
   • シークレット：.secrets が存在する場合、act は自動的に読み込みます （または --secret-file を渡します）。シークレットを捏造しないでください — シークレットがない場合は環境によるスキップであり、失敗ではありません。

5. 結果を読み取り、二種類の失敗を区別します。 act の終了コードでは区別できないためです。 ログのマーカーを確認します。

   • 成功 — ジョブが ✅ ／ Job succeeded で終了： ワークフローがローカルで実際に実行されました（act が対応する範囲内）。
   • ワークフロー自体の失敗 — 「Set up job」ではなく、ワークフローのステップが そのロジックによりゼロ以外のコードで終了した場合です。 内容を示して修正を提案しますが、コミットは妨げません。
   • 環境／非対応による失敗 — 実行を開始できなかった場合です： failed to start container、Error response from daemon、 unable to find image、または macos／windows ランナー用のイメージがない、 fatal ... EOF（イメージのプロンプト）、シークレット不足、OIDC、ソケット、アーキテクチャなど。 標準ツールの command not found も該当します — ワークフローではなく Medium イメージにそのツールがないことがほとんどです。 イメージの内容は確認できないため、デフォルトでは環境の問題として扱い、 重要であればオペレーターに確認します。 これらは失敗ではなく、理由を添えて「ローカルでは未確認」と報告します。
   • 判断できない場合 — オペレーターに確認します。

6. 結果にかかわらず、act を理由にコミットを妨げてはいけません。 実行後（またはスキップ後）は、コミットを続行します。

act がない場合のインストール

mise でインストールします — Docker は別途必要な依存関係であり、 Docker なしでは act を実行できないことにも留意してください。 mise.toml の [tools] 配下に記述します。

[tools]
act = "<version>"

mise latest act で <version> を解決します （すべてのバージョン：mise ls-remote act）。latest は使わず、完全なバージョンを固定します。 名前 act は aqua を通じて aqua:nektos/act に解決されます。 brew、go install、curl パイプのスクリプトは使わないでください。 その方法で act をインストールできない場合、または Docker が利用できない場合は、 オペレーターに伝えて実行をスキップします。

対応範囲を正直に伝える — act は CI ではありません

act の実行が成功しても、それはスモークテストであり、実際の CI が成功する証明ではありません。 act は macos／windows ランナー、OIDC、 環境および環境スコープのシークレットを実行しません。 また、同時実行制御、タイムアウト、continue-on-error、 ステップサマリー、アノテーションは無視します。 キャッシュとサービスへの対応も一部に限られます。 act は「ローカルで実行を開始できるか」を確認するものとして扱い、 正しい結果の基準は実際の CI とします。

対象外

• 実際の CI の置き換え（act はスモークテストです。上記の対応範囲を参照してください）。
• シークレット／認証情報の提供や捏造。
• ローカルでは動作しない実行の強制 — 無理に実行せず、その旨を報告します。

報告

実行後、どのワークフローまたはジョブが実行されたか、 それぞれの結果（成功／実際の失敗／理由付きのローカル未確認）、 およびいずれの場合もコミットは妨げられないことを伝えます。