GitHub Actions をローカルで実行！ nektos/act の紹介

はじめに

GitHub Actions を使っている方は多いと思います。新しいワークフローを作るとき、GitHubにpushして動作確認しなければいけなくて、手間が多いですよね。

そこで、 nektos/act を使うと、自分のマシン上でワークフローを実行できます。
公式サイトによれば、

• Fast Feedback: コミットやプッシュなしで動作確認ができるため、開発効率を向上させる。
• タスクランナーとして利用: make やシェルスクリプトのようなタスクランナーの代替として使うことも可能。

というわけ。

▶ GitHub: https://github.com/nektos/act
▶ 公式ドキュメント: https://nektosact.com/

セットアップ

macOS の場合、Homebrew で簡単にインストールできます。

brew install act

その他、各種のパッケージマネージャー向けに配信されています。
また、act はgo言語で書かれているので、ビルド環境を整えれば自分でビルドすることもできます。
詳細は公式の Installation をどうぞ。

▶ Installation https://nektosact.com/installation/index.html

実行する

リポジトリのルートディレクトリで、 act コマンドを使うことで実行できます。

どのようなCIが存在するかチェック

act --list

基本的な使い方は act [event name] です。例えば、以下のようにして、pushイベントを発火させます。

act push

わーお！これだけで GitHub Actions をローカルで動かせちゃうのね！

さらに詳しく

nektos/act は GitHub とは無関係なプロジェクトだということに注意が必要です。GitHub Actions を完全再現するわけではありませんし、GitHubと連携する機能もありません。

actions/checkout や actions/setup-node といった公開されているActionは動かすことができます。

他にもいくつか注意点がある。

ランナーについて

act は Docker に依存しているので、あらかじめホストマシンにDockerをインストールしておく必要があります。
初回起動時は、ランナーと呼ばれる専用の仮想環境をプロビジョニングする必要があり、以下のような選択肢が表示されて、ランナーを選択するように促されます。
見ての通り、Largeサイズは膨大なストレージが必要です。だいたいの用途では、Mediumで良いのではないでしょうか。

いずれの場合も、GitHub Actionsと差異がある可能性に注意です。

▶ 公式ドキュメント ランナー https://nektosact.com/usage/runners.html

プラットフォームについて

GitHub Actions は、x86_64環境の仮想マシン上で実行されます。一方、macOSは arm64環境ですので、注意が必要です。
本当に軽微なスクリプトなら気にしなくても良いですが、ビルドやテストなど、ジョブによってはプラットフォームが重要になってきます。
act に --container-architecture フラグを渡すことでランナーのアーキテクチャを指定することができます。例えば、x86_64環境でpushイベントを発火させるには、以下のようなコマンドを使います。

act push --container-architecture linux/amd64

これらのオプションフラグは、毎回指定するのが大変ですので、ファイルに格納しておくことも可能です。

環境変数について

上で触れた通り、actはGitHubと連携するわけではありませんので、GitHubの環境変数やシークレットに依存している場合は自分でactに渡してやる必要があります。
--var, --var-file, --secret, --secret-file といったオプションが存在しており、コマンドラインで直接変数を渡すか、.env形式のファイルから渡すことが出来ます。

ローカルにある.envファイルを渡す例です。

act push --secret-file .env

使えない機能も

開発が進むにつれてサポートされる機能が増えていく可能性がありますが、GitHubにあるいくつかの機能は使えません。

少し試した限り、ステップの概要（GITHUB_STEP_SUMMARY）や通知メッセージ（::notice）といった機能は作動しないようでした。これらは、レイヤーが違う、と言えましょう。

if による条件判定や、 uses を使った他ワークフローの呼び出しなど、基本的な機能には対応しています。

診断

act は、ローカルマシンのDockerで動作するので、これを利用して、ワークフローが思った通りに動かないときには、直接コンテナに乗り込んで診断することも可能です。例えば、ワークフロー内で run: sleep 1800 のようにして動きを止めたうえで以下のスクリプトを使うと、コンテナに入ることが出来ます。ただし、このシェルには環境変数が渡りません。

docker exec -it `docker ps | grep act | awk '{print $1}'` /bin/bash

actの活用

私がactのことを知ったきっかけとなった、Giteaも紹介。

私は趣味で家庭内Gitリポジトリを立てています。これには、セルフホスト版の Gitea を使っています。Giteaは、go言語で書かれたプライベートなGitHubのようなもので、とても小さいフットプリントで動作します。

▶ Gitea公式サイト https://about.gitea.com/

Gitea には、 Act Runner と呼ばれるCIの仕組みが組み込まれています。名前の通り内部では act が使われています。GiteaがそれにアクセスするためのUIを提供し、かなりGitHub Actionsに似たUI/UXになっています。

GitHub のセルフホステッドランナーのように、外部化されたランナーをGiteaに登録する仕組みになっています。

(図: Giteaドキュメントより)
(上図で言う Act runner というのがGiteaのシステムで、RPCで本体と通信して、actを管理します。Docker API を使ってコンテナを作り出す仕組みで、Jobがactだと思います）

私は、趣味の家庭内IoT機器のポーリングや、ブログのビルドに利用しています。
実務では、セルフホスト要件が厳しいプロジェクトで、ビルドシステムを独自に構築したい場合、良い選択肢になると思います。

まとめ

nektos/act を使えば、GitHub Actions のワークフローをローカル環境で素早くテストでき、開発の効率が向上します。

ポイント:

• GitHub Actions をローカルで実行できる
• GitHub との違いに留意
• 環境変数やシークレットを手動設定する必要あり

GitHub Actions を効率的に活用するために、ぜひ試してみてください！