ハクソク

世界を動かす技術を、日本語で。

GitHub Actionsをローカルで実行する

2025年5月16日原文(github.com)

概要

  • GitHub Actions をローカルで実行できるツール act の紹介
  • 迅速なフィードバックと Makefile 代替としての利用が可能
  • VS Code拡張機能 でエディタ内から直接操作可能
  • Dockerを活用して GitHub本番環境 に近い実行環境を再現
  • 導入・貢献方法やサポートチャネルも案内

GitHub Actionsをローカルで動かす：actの活用提案

  • act は、GitHub Actionsを ローカル環境 で実行するためのツール 提案

  • 主な目的は 2つ ・迅速なフィードバックを得ること ・Makefileの代替として ローカルタスクランナー 化すること 提案

ローカル実行のメリット

  • .github/workflows/の変更を 即時テスト できるため、毎回commit/pushする必要がない 確認

  • 環境変数 や ファイルシステム がGitHub本番環境と一致するよう自動設定 確認

  • Makefileの繰り返し記述を省略し、 ワークフロー定義 をそのままタスクランナーとして利用可能 提案

VS Code拡張機能による運用

  • GitHub Local Actions というVS Code拡張機能を使うことで、actをエディタ内から直接操作可能 確認

  • ワークフローの ローカル実行・テスト をエディタから離れずに完結できる 効率化

actの動作仕組み

  • actは.github/workflows/内のGitHub Actions定義を読み取り、 実行すべきアクション を決定する 流れ把握

  • Docker APIを利用し、 必要なイメージ をpullまたはbuildすること 実行手順

  • ワークフロー内で定義された 依存関係 に基づき、実行経路（execution path）を決定すること 実行手順

  • Docker APIを用い、各アクションに対して コンテナ を起動し、準備したイメージで実行すること 実行手順

  • 環境変数 や ファイルシステム はGitHub本番と同様に自動構成 再現性確保

サンプルとドキュメント

  • Sample Repository で実際の動作例を確認可能 体験

  • 詳細な利用方法は act User Guide でドキュメント化 参照

サポートと貢献

  • Gitter で質問・サポートを受け付け 相談

  • 貢献希望者は contributing guidelines を参照し、開発参加すること 参加

ソースからの手動ビルド手順

  • Goツールチェーン（1.20+） をインストールすること 準備

  • リポジトリを git clone で取得すること 準備

  • make testで ユニットテスト を実行すること 確認

  • make installで ビルド・インストール を行うこと 導入

関連リンク

Hackerたちの意見

今週、Rubyテストの変なCIエラーをデバッグするために、もう一度これに挑戦してみたんだけど、MシリーズのMacを使ってるからプラットフォームの不一致があってさ。それに、アクションランナーとしてデポ画像を使ってるから、ドライランの段階を超えて動かすことができなかった。CIランナーとローカルのDockerイメージの間には、ほんとにたくさんの違いがあるんだよね。catthehackerのイメージも試してみたけど、15GB以上あって、それでも動かなかった。結局、諦めちゃった。

└

それよりもひどいのは、圧縮されて20GB、展開すると60GBになること。とはいえ、VMのディスクスペースが足りなくなると、意味のあるエラーは出ない（まあ、12ヶ月前はそうだった）し、起動に失敗するだけなんだよね。（多分colima特有かもしれないけど、Dockerはアンインストールしたからわからない）ローカルではうまくいくこともあれば、実際のアクションでは失敗することもあるし、その逆もある。とはいえ、全体的には進展を促進するのが楽になったかな。

└

こんなのが役立つかもしれないよ。実行中のインスタンスにSSHで入って、正確なコンテキストでデバッグできるからね：https://docs.warpbuild.com/tools/action-debugger

└

デバッグしようとしたアクションで運が良かったけど、ランタイムの差が大きすぎて100%信頼するのは無理だな。残念だけど、このツールは結構いいと思うんだよね。

└

ローカルでGHアクションをデバッグしようとした時の経験に似てるな。今までに2回試してみたけど、何GBもあるイメージをダウンロードして、色々インストールして、結局はよくわからない設定や環境の問題で行き詰まっちゃった。ローカルでLinuxも動かしてたから、これが一番うまくいくと思ったんだけど。もう一度試す気にはなれないし、もしすごく遅いCIとか、何か理由で頻繁に更新が必要なGHアクションがない限り、リモートでCIが動くのを待つ方がいい気がする。

└

GH Actionsは、変なことしなければずっと完璧に動いてる。先週、カスタムサーバーからGH Pages + GH Actionsに戻したら、ビルドフェーズの後に出力ディレクトリが必要な機能が壊れちゃった。どう直せばいいかわからない。多分簡単なんだろうけど、もう疲れちゃった。

└

ChristopherHXは、ランナーの中からルートファイルシステムをtarballにパッキングして直接作成されたDockerイメージを公開してる。ただ、イメージはめちゃくちゃ大きい。https://github.com/ChristopherHX/runner-image-blobs/pkgs/con...

└

Apple SiliconでのRubyの経験は全然スムーズじゃなかった。問題を完全に解決する唯一の方法は、最新のRubyリリースを実行して、その影響に対処することだったよ。GHアクションが最新のRubyバージョンを実行してるとは思えないな。

└

これは本当にアクションのロジックをデバッグするためだけだよね？私のチームでは、NixがCIジョブがやる面白いことのほとんどをカプセル化するのにうまく機能してるみたい。ローカルバージョンを実行するために仮想化は使ってないし、アーキテクチャの不一致の問題にも直面してないよ。

私の経験（そしてこの投稿に寄せられたコメントにも反映されてるけど）、複雑なCIワークフローをローカルで動かそうとするのは、かなり絶望的な試みだと思う。完全にコンテナ化されたワークフローがあれば近づけるかもしれないけど、それでもCI特有の環境変数をすべて揃えるのは簡単じゃないし、ワークフローがタスク間で何かを調整してる場合（例えば、一つのタスクがアーティファクトをアップロードして、別のタスクがそのアーティファクトを使う）には、CIで何が起こっているのかを正確に再現するのは難しいよ。私の会社（RWX）はGitHub Actionsの競合を作っていて、意図的にローカル実行をサポートしてないんだ。代わりに、git pushせずにローカルマシンからリモートビルドを簡単に開始できるようにして、実行中のタスクの前後でSSHセッションを取得して、ワークフローが実行されている正確なビルド環境を確認できるようにしてる。

└

ローカル開発には.envファイルとmiseを使えるよ。https://mise.jdx.dev/environments/#env-file 俺はdaggerを使ってこれらの.env/mise環境変数を読み込んで、テストコンテナにダミー値を注入してる。プロダクションはシークレットマネージャーで管理してるよ。

警告：actはDockerを使うなら素晴らしいけど、Podmanはサポートしてないよ。Podmanのサポートや互換性、回避策に関する問題や議論は、簡潔なメッセージで閉じられてる。オープンソースプロジェクトとしては珍しいね。

Hacker Newsで議論の続きを見る