GitHub ActionsをActでローカルに実行する方法

GitHub Actionsは、開発者がリポジトリ内でワークフローを自動化する方法を革新しました。継続的インテグレーションおよび継続的デプロイメント（CI/CD）パイプラインから、イシューレベルの自動化やリリースノートの生成まで、ActionsはGitHub内でソフトウェア開発ライフサイクルを直接管理するための強力で統合的な方法を提供します。

しかし、これらのワークフローを開発・テストすることは時には煩わしく感じられます。従来のサイクルには以下のステップが含まれます：

ワークフローファイル（通常は.github/workflows/にあります）を変更する。
これらの変更をコミットする。
それらをGitHubリポジトリにプッシュする。
GitHubのランナーがジョブを取得して実行するのを待つ。
変更が機能したか、エラーを引き起こしたかを確認するためにGitHubウェブサイトでログを分析する。

このプロセス、特に待機時間およびローカルエディタとGitHub UI間のコンテキストスイッチは、開発のスピードを大幅に低下させる可能性があります。特に複雑なワークフローやトリッキーな問題のデバッグの際には顕著です。もし、プッシュする前にActionsをテストできたらどうでしょうか？

まさにそこでactが登場します。そのキャッチフレーズが示すように、「世界を考え、actをローカルで実行する」。actは、Dockerコンテナを使用してGitHub Actionsワークフローをローカルで実行するために設計されたオープンソースのコマンドラインツールです。GitHub Actionsが提供する環境をシミュレートし、毎回小さな変更をコミットしてプッシュすることなく、ワークフローを迅速にテストして反復することができます。

💡

優れたAPIテストツールが欲しいですか？美しいAPIドキュメントを生成します！

開発者チームが最大の生産性で協力できる統合型のオールインワンプラットフォームが欲しいですか？

Apidogはすべての要求を満たし、Postmanをより手頃な価格で置き換えます！

button

なぜ`act`を使ってGitHub Actionsをローカルで実行するのか？

actを開発ワークフローに組み込むメリットは非常に大きいです：

迅速なフィードバック：これは主な利点です。コミット・プッシュ・待機・デバッグのサイクルの代わりに、ローカルで変更を加えた直後にワークフローを即座に実行できます。数秒または数分でフィードバックを得られ、数分または数十分を待つことはありません。これは.github/workflows/ファイルの開発とデバッグプロセスのスピードを劇的に向上させます。
ローカルタスクランナー：多くのプロジェクトは、make、npm scripts、またはカスタムシェルスクリプトのようなツールを使用して共通の開発タスク（ビルド、テスト、リンティングなど）を定義します。actを使用することで、これらのタスクを統合できます。ビルド、テスト、およびその他のプロセスをGitHub Actionsジョブとして定義し、その後actを使用してローカルでこれらのジョブを実行することができます。これにより、重複を減らし、ローカル開発環境とCI/CDパイプライン間の一貫性が保証されます。タスクは一度ワークフローファイルで定義され、どこでも同じように（または非常に類似して）動作します。
オフライン開発：常時インターネット接続がなくても基本的なワークフロー構文やロジックをテストできます（ただし、初回のイメージダウンロードや特定のアクションでは接続が必要な場合があります）。
コスト削減：GitHubは公開リポジトリに対する手厚い無料利用枠とプライベートリポジトリに対して妥当な料金を提供していますが、開発中に複雑または長いワークフローを繰り返し実行すると、ランナーミニッツを消費する可能性があります。ローカルでテストすることで、この使用を避けることができます。
デバッグ能力：GitHub上で失敗したアクションをデバッグするのは、しばしば追加のログを追加し、プッシュして待つことを伴います。actを使用すれば、ローカル環境を検査したり、ボリュームをマウントしたり、起動するDockerコンテナ内で高度なデバッグ技術を使用したりすることができます。

`act`はどのように機能するのか？

actのメカニズムを理解することで、効果的に使用したり、潜在的な問題をトラブルシューティングしたりすることができます。以下にその操作の概要を示します：

ワークフローパース：リポジトリのルートディレクトリでactコマンドを実行すると、.github/workflows/ディレクトリ内のワークフローファイル（YAMLファイル）をスキャンします。
イベントトリガーシミュレーション：デフォルトではactはpushイベントをシミュレートしますが、pull_requestやworkflow_dispatchなどの他のイベントを指定することもできます。指定されたイベントおよびワークフローファイルで定義されたon:トリガーに基づいて、実行すべきワークフローやジョブを決定します。
依存関係分析：actは、ワークフロー内のジョブ間の依存関係（needs:キーワードを使用）を分析し、正しい実行順序を決定します。
Dockerイメージ管理：各ジョブについて、actは指定されたランナー環境を特定します（例：runs-on: ubuntu-latest）。その後、これを特定のDockerイメージにマッピングします。actはDocker APIを使用して：

イメージをプル：必要なランナーイメージと、コンテナアクションで使用されるDockerイメージをダウンロードします（uses: docker://...）。デフォルトでは、特に設定されていない限り、各実行時にイメージをプルします。
イメージをビルド（必要に応じて）：アクションがローカルDockerfileを指している場合（例：uses: ./path/to/action）、actはローカルでDockerイメージをビルドできます。

コンテナ実行：actはDocker APIを使用して、各ステップに対してコンテナを作成し実行します。これらのコンテナをGitHub Actions環境にできる限り近づけるように構成します：

環境変数：標準のGitHub Actions環境変数（GITHUB_SHA、GITHUB_REF、GITHUB_REPOSITORY、CIなど）が注入されます。
ファイルシステム：リポジトリのコードは、コンテナの作業ディレクトリ（/github/workspace）にマウントされます。ステップによって生成されたファイルは、次のステップのためにコンテナ内に保存されます。
ネットワーク：コンテナは通常、Dockerブリッジネットワーク上で実行され、必要に応じて通信を行います（ただし、ネットワークの詳細はGitHubの環境とは異なる場合があります）。

ログストリーミング：actは、実行中のコンテナからのログを直接ターミナルにストリーミングし、実行の進行状況やエラーについてリアルタイムのフィードバックを提供します。

基本的に、actはローカルのDockerコンテナを編成して、GitHub Actionsワークフローの実行フローと環境を再現します。

前提条件：Dockerのインストール

actの主要な依存関係はDockerです。actは、ワークフローステップを実行するために必要な隔離された環境を作成するためにDockerエンジンを利用します。actをインストールする前に、動作するDockerインストールがシステム上に必要です。

Dockerをインストール：お使いのオペレーティングシステムに関する公式の指示に従ってください：
macOS：Docker Desktop for Mac
Windows：Docker Desktop for Windows（WSL 2またはHyper-Vが必要）
Linux：お使いのディストリビューションに特有の指示に従ってください（例：Ubuntu、Fedora、Debianなど）。Dockerコマンドをsudoなしで実行できるように、ユーザーをdockerグループに追加することを確認してください。
Dockerを確認：インストール後、ターミナルを開いてdocker run hello-worldを実行します。このコマンドは、小さなテストイメージをダウンロードし、コンテナで実行します。正常に実行されれば、Dockerのセットアップが準備完了です。

インストール`act`

Dockerが実行されている状態になったら、actをインストールできます。これを行う方法はいくつかあり、オペレーティングシステムや好みによります。

1. Homebrew（macOSおよびLinux）

Homebrewパッケージマネージャを使用している場合、インストールは簡単です：

brew install act

これにより、最新の安定版がインストールされます。絶対に最新の開発版が必要な場合（コンパイラが必要になる場合があります）、次のコマンドを使用できます：

brew install act --HEAD

2. GitHub CLI拡張（macOS、Windows、Linux）

すでにGitHub CLI（gh）を使用している場合、actを拡張機能としてインストールできます：

gh extension install nektos/gh-act

インストール後、ghコマンドを使用してactを呼び出します：

gh act          # 単に'act'の代わりに
gh act -l
gh act pull_request

3. Chocolatey（Windows）

Windows上のChocolateyパッケージマネージャのユーザー向け：

choco install act-cli

（注：一部の情報源ではactの代わりにact-cliが記載されている場合があります。問題が発生した場合は、Chocolateyコミュニティリポジトリで最新のパッケージ名を確認してください。）

4. Scoop（Windows）

Windows上のScoopパッケージマネージャのユーザー向け：

scoop install act

5. WinGet（Windows）

Windowsパッケージマネージャ（winget）のユーザー向け：

winget install nektos.act

6. Linuxスクリプトインストーラー

パッケージマネージャ経由での簡単なアクセスが難しいLinuxディストリビューション用に便利なスクリプトが用意されています：

curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

（注：常にsudoに直接スクリプトをパイプするときは注意してください。セキュリティ上の懸念がある場合は、最初にスクリプトの内容を確認してください。）

7. その他の方法（Arch、COPR、MacPorts、Nix）

pacman（Arch）、COPR（Fedora）、MacPorts、Nixなどの他のパッケージマネージャについてのインストール手順は、公式のactドキュメントに記載されています：

確認：

インストール後、新しいターミナルウィンドウを開き、以下を実行します：

act --version
# あるいは、gh拡張を使用している場合：
gh act --version

これにより、インストールされたactのバージョンが表示され、インストールが成功したことが確認されます。

初期設定：ランナーイメージ

プロジェクトディレクトリ内でactを初めて実行すると、デフォルトのランナーイメージサイズを選択するように促される場合があります。GitHub Actionsは、リソースと事前にインストールされたソフトウェアの異なるランナーを提供します。actはこれを、さまざまな基本Dockerイメージを使用して模倣しようとします。

通常、以下のような選択肢が提示されます：

? 使用したいactのデフォルトイメージを選択してください：

  - Micro：Node.jsサポートのある最小限のイメージ（約200MB）docker.io/node:16-buster-slim
  - Medium：基本ツールを備えたActイメージ（約500MB）ghcr.io/catthehacker/ubuntu:act-latest
  - Large：GitHub Actionsランナーイメージ（約17GB）ghcr.io/catthehacker/ubuntu:full-latest

デフォルトのイメージは？ [Medium]:

Micro：公式のNode.jsスリムイメージ（node:16-buster-slimやnode:16-bullseye-slimなど）に基づいています。非常に小さく、ダウンロードが迅速ですが、Node.jsと最小限のシステムライブラリしか含まれていません。アクションがNode.jsのみを必要とする場合や、すべての依存関係を自身でインストールする場合に適しています。
Medium：ユーザーcatthehackerが提供しています（例：catthehacker/ubuntu:act-latest、catthehacker/ubuntu:act-22.04）。これらのイメージにはGitHubランナーで見られるより一般的なツールが含まれていますが、それでも比較的軽量です（約500MB）。これは多くの一般的なユースケースに適しており、機能とサイズのバランスが良いため、推奨されるデフォルトです。
Large：同様にcatthehackerから（例：catthehacker/ubuntu:full-latest、catthehacker/ubuntu:full-22.04）。これらは実際のGitHubホスティングされたランナーのファイルシステムダンプから作成されており、ほぼすべてのプレインストールされたソフトウェアが含まれています。互換性は最高ですが、非常に大きく（多くの場合>17GB）、初回ダウンロード時間が長くなり、ディスクスペース使用量も大きくなります。

推奨：最初はMediumイメージを使用してください。これは優れたバランスを提供し、多くの一般的なユースケースに適しています。欠落しているソフトウェアに関する問題が発生した場合は、ワークフローステップ内でソフトウェアをインストールするか、その特定のランナーのためにLargeイメージを使用するように切り替えることができます（詳細は後述）。

actはあなたの選択を設定ファイル（~/.actrc）に保存します。後でこのファイルを編集するか、設定が必要なディレクトリでactを再実行することでデフォルトを変更できます。

コア`act`の使用法：ワークフローを実行する

インストールと設定が完了したら、actを使用するのは比較的簡単です。ターミナルでプロジェクトのルートディレクトリ（.githubフォルダを含むディレクトリ）に移動します。

1. デフォルトイベント（push）を実行する

最も簡単なコマンドは、デフォルトのpushイベントによってトリガーされるワークフローを実行します：

act
# または
gh act

actはあなたのワークフローを解析し、on: pushでトリガーされるジョブを特定し、必要なDockerイメージをプルします（キャッシュにない場合）、そしてジョブを実行します。

2. 利用可能なワークフローとジョブのリストを表示する

actが認識しているワークフローとジョブを確認するには、次のようにしてデフォルトのイベント用に動作するものを確認します：

act -l
# または
gh act -l

これにより、次のようなリストが出力されます：

Stage  Job ID        Job name      Workflow name  Workflow file  Events
0      build         Build         CI Pipeline    ci.yaml        push
1      test          Test          CI Pipeline    ci.yaml        push
1      lint          Lint          Code Quality   codeql.yaml    push,pull_request

3. 特定のジョブを実行する

ワークフローから単一のジョブだけをテストしたい場合は、-jフラグを使ってジョブID（act -l出力から）を指定します：

act -j build
# または
gh act -j build

4. 特定のイベントをトリガーする

ワークフローは、push以外のイベントでもトリガーされます。これらのイベントをシミュレートするには、イベント名をactの引数として指定します：

# プルリクエストイベントをシミュレート
act pull_request

# workflow_dispatchイベント（手動トリガー）をシミュレート
act workflow_dispatch

# スケジュールイベントをシミュレート
act schedule

# リリースイベントをシミュレート
act release -e event.json # 必要に応じてイベントペイロードの詳細を提供

actは、指定されたイベントでon:を実行するように設定されたワークフローやジョブのみを実行します。

5. workflow_dispatchに対する入力を渡す

workflow_dispatchによってトリガーされたワークフローは、入力を受け入れることができます。これらは--inputフラグや-iを使って提供できます：

# ワークフローに'環境'という名前の入力があると仮定
act workflow_dispatch --input environment=staging

6. シークレットの取り扱い

GitHub Actionsワークフローは通常、シークレット（APIキーやトークンなど）に依存しています。actは自動的にあなたのGitHubシークレットにアクセスしません。ローカルでそれらを提供する必要があります。

インタラクティブプロンプト：-sフラグを使用します。actはワークフローで定義された各シークレットの値を入力するように促します。

act -s MY_SECRET_TOKEN -s ANOTHER_SECRET

または、act -sだけで全てのシークレットの入力を促します。

環境変数：シークレットは通常、SECRET_で接頭辞された環境変数として渡されます。actを実行する前にシェル内で定義できます：

export SECRET_MY_SECRET_TOKEN="your_value"
act

シークレットファイル：KEY=VALUEペアを含むファイル（例：.secrets）を作成します：

MY_SECRET_TOKEN=your_value
ANOTHER_SECRET=another_value

その後、--secret-fileフラグを使用してactを実行します：

act --secret-file .secrets

（このファイルは、シークレットをコミットしないように.gitignoreに追加することを確認してください！）

7. 変数と環境変数の取り扱い

ワークフロー変数：ワークフローのレベルで定義された変数（vars:コンテキスト、ただしactでの完全なvarsコンテキストサポートには制限がある場合があります）に値を提供できます。--varフラグまたは--var-fileを使用して、シークレットと同じく提供します。
環境変数：ワークフロー実行のカスタム環境変数を設定するには、--envフラグまたは--env-fileを使用します。

act --env NODE_ENV=development --env CUSTOM_FLAG=true
act --env-file .env_vars

ランナー環境とイメージの管理

デフォルトのランナーイメージ（Micro、Medium、Large）は多くのシナリオをカバーしますが、さらなるコントロールが必要な場合がよくあります。

1. デフォルトイメージの制限

デフォルトのactランナーイメージ（特にMicroおよびMedium）は、GitHubが提供する環境には一致しません。ワークフローが期待する特定のツール、ライブラリ、またはシステムサービス（例：Dockerコンテナにsystemdがない）を欠いている可能性があります。Largeイメージは高い忠実度を提供しますが、サイズが大きいという重大な欠点があります。

2. -Pで代替イメージを指定する

ジョブがデフォルトイメージに存在しない特定の環境またはツールセットを必要とする場合、-P（プラットフォーム）フラグを使用して特定のプラットフォームに対して異なるDockerイメージを使用するようにactに指示できます。

フォーマットは-P <platform>=<docker-image>です。

<platform>：ワークフローのruns-on:ディレクティブで使用されるラベル（例：ubuntu-latest、ubuntu-22.04、ubuntu-20.04）。
<docker-image>：使用するDockerイメージのフル名（例：node:18、python:3.10-slim、mcr.microsoft.com/devcontainers/base:ubuntu）。

例：

# ubuntu-22.04上で実行されるジョブのためにLargeイメージを使用
act -P ubuntu-22.04=ghcr.io/catthehacker/ubuntu:full-22.04

# ubuntu-latestジョブのために特定のNode.jsバージョンを使用
act -P ubuntu-latest=node:18-bullseye

# nektos/act-environmentsからのより完全なイメージを使用（非常に大きい！）
# 警告：nektos/act-environments-ubuntu:18.04は>18GBです
act -P ubuntu-18.04=nektos/act-environments-ubuntu:18.04

# ワークフローがそれらを使用している場合、複数のプラットフォームを指定
act -P ubuntu-20.04=node:16-buster -P ubuntu-22.04=node:18-bullseye

3. ローカルランナーイメージの使用（--pull=false）

デフォルトでは、actは実行のたびに指定されたDockerイメージの最新バージョンをプルしようとします。カスタムランナーイメージをローカルで構築した場合や、キャッシュしている正確なバージョンを使用していることを確認したい場合は、この動作を無効にできます：

act --pull=false
# またはオフラインモードを使用
act --action-offline-mode

これにより、actはローカルに利用可能なイメージを使用し、存在しない場合のみプルを試みるようになります。

4. ホスト上でネイティブに実行（-self-hosted）

macOSまたはWindowsを対象としたワークフロー（runs-on: macos-latestまたはruns-on: windows-latest）の場合、actを同じホストオペレーティングシステムで実行している場合は、ランナー自身にDockerコンテナを使用しないように指示できます。その代わり、ステップをホストマシン上で直接実行します。Dockerの互換性に問題がある場合や、ホストリソースに直接アクセスする必要がある場合に便利です。

# macOSホスト上でmacos-latestジョブを直接実行
act -P macos-latest=-self-hosted

# Windowsホスト上でwindows-latestジョブを直接実行
act -P windows-latest=-self-hosted

注意：ホスト上で直接実行すると、Dockerが提供する隔離がバイパスされます。ジョブ内のステップはファイルシステムにアクセスでき、ホスト環境を変更する可能性があります。このオプションを使用する際は注意してください。サービスコンテナやコンテナアクションなど、ジョブ内で明示的にDockerコンテナを使用するステップは、引き続きDockerを使用します。

制限事項と考慮事項

actは非常に便利ですが、その制限を認識することが重要です：

完全なレプリカではない：actはGitHub Actions環境をシミュレートしますが、同一ではありません。ネットワーキング、利用可能なシステムサービス（例：Dockerコンテナ内にはsystemdが容易にはありません）、特定のハードウェアリソース、事前にインストールされたツールの正確なセット（非常に大きなランナーイメージを使用しない限り）などに違いがあります。特に、基盤となるOSや特定のGitHub機能と大きく関与する複雑なワークフローは、actとGitHubで異なる動作をする可能性があります。
コンテキストの違い：githubコンテキストの一部が不完全であるか、ローカルで実行されるとデフォルトまたはモック値が含まれる場合があります。secretsコンテキストは常に明示的な入力が必要です。varsコンテキストサポートは、ライブのGitHub環境に比べて制限がある可能性があります。
同時実行：actは通常、needs依存関係に基づいてジョブを逐次的に実行します。マトリックス戦略を使用して複数のランナーで独立したジョブを同時に実行するGitHubの能力を完全には再現しません（ただし、actはマトリックスジョブを実行するサポートを提供していますが、通常はローカルで逐次実行されます）。
ホステッドサービス：actions/cacheのような機能は、GitHubの統合キャッシングサービスに比べて異なる動作をするか、特定の設定を必要とする場合があります。ワークフローで定義されたサービスコンテナは機能するはずです、actはそれらにもDockerを利用します。
プラットフォームの可用性：Dockerがサポートするホスト（Mac、Windows、Linux）上でしかLinuxベースのジョブをDocker内で実行できません。macos-latestジョブを実行するには、理想的にはmacOS上でactが必要です（またはmacOS上で-self-hostedフラグを使用）。同様に、windows-latestジョブには通常、Windows上でのactが必要です（またはWindows上で-self-hosted）。DockerはWindowsコンテナをWindows上で実行できますが、actは主にLinuxコンテナを対象としており、最も安定したサポートを提供しています。

推奨：actを迅速な開発、構文チェック、基本的なロジックテスト、および個々のジョブやステップの反復に使用してください。特にデプロイメントパイプラインに重要な変更をマージする前には、必ずGitHub上でワークフローを実行して最終検証を行ってください。公式のactドキュメントを確認して、詳細なサポートマトリックスと既知の問題を確認してください。

結論

GitHub Actionsをローカルでテストすることは、生産性を大幅に向上させ、潜在的に遅く煩わしいデバッグサイクルを迅速かつ反復的なプロセスに変えます。act CLIツールは、Dockerを活用してローカルマシン上でGitHub Actionsランナー環境をシミュレートする信頼性と柔軟性のある方法を提供します。

actをワークフローに統合することで、次のような利点が得られます：

フィードバックループが迅速化される。
テストのためにGitHubにプッシュする必要が減少する。
アクション定義をローカルタスクランナーとして利用できる。
デバッグ能力が向上する。

制限があり、ライブGitHub環境の完璧な1:1置き換えではありませんが、actは幅広いユースケースをカバーし、信頼性のある効果的なGitHub Actionsワークフローの開発に関する摩擦を大幅に減らします。インストールして、既存のワークフローをローカルで実行し、グローバルに考え、ローカルで行動するという利点を体験してください。

💡

button

なぜactを使ってGitHub Actionsをローカルで実行するのか？

actはどのように機能するのか？