actの使い方完全ガイド【インストールから応用まで】

GitHub Actionsは、CI/CDパイプラインを自動化するための強力なツールです。しかし、ワークフローの変更をテストするたびに、コードをコミットし、プッシュし、リモートリポジトリでのCI/CD実行を待つ必要があると、開発効率は低下します。小さな変更でも数分、ときには数十分を要し、このフィードバックループの長さは開発者の大きなストレスとなるでしょう。

このような「プッシュ・アンド・待つ」のサイクルは、開発時間とCI/CDサービスの利用料金の両方を無駄にしてしまいます。特に複雑なワークフローや新しいアクションを開発する際には、試行錯誤の回数が増え、そのたびに待ち時間が発生するのは避けたいものです。

そこで登場するのが nektos/act（以下、act）です。actは、GitHub Actionsをローカル環境で実行できるツールです。これを使えば、リモートリポジトリにプッシュすることなく、手元の環境でワークフローの動作を即座に確認できます。開発のスピードは劇的に向上し、CI/CDの利用料金も節約できます。

actとは

actは、GitHub ActionsをローカルのDocker環境で実行するためのコマンドラインツールです。わずか30秒でその概要を理解できます。

このツールが誕生した背景には、GitHub Actionsのフィードバックループの長さという課題がありました。ワークフローの変更をリモートでテストする手間をなくし、開発者がより迅速にイテレーションできるよう支援するために開発されました。

actの主な利点は以下の2点です。

• 高速なフィードバック: .github/workflows/ ファイルや組み込みアクションの変更をテストする際、コミットやプッシュが不要になります。ローカルで即座に実行し、結果を確認できます。actは、GitHubが提供する環境変数やファイルシステムを忠実に模倣します。
• ローカルタスクランナー: makeコマンドのように、ローカルのタスクランナーとしても活用できます。.github/workflows/ で定義したGitHub Actionsを、ローカル環境でのタスク実行に再利用できます。これにより、Makefileのような重複する設定を避けることが可能です。

actは、ワークフローファイルを読み込み、実行する必要があるアクションを特定します。次に、Docker APIを使用して必要なイメージをプルまたはビルドします。そして、定義された依存関係に基づいて実行パスを決定し、Dockerコンテナ内で各アクションを実行します。この一連のプロセスにより、GitHub Actionsランナーとほぼ同じ環境がローカルに再現されます。

インストール方法

actは、Dockerを利用するため、事前にDocker DesktopまたはDocker Engineのインストールが必要です。

各OSでのインストール方法は以下の通りです。

macOS

Homebrewを利用してインストールできます。

brew install act

Linux

Homebrewまたはcurl経由でインストールできます。

Homebrewを使用する場合:

brew install act

curlを使用する場合:

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

Windows

ScoopまたはChocolateyを利用してインストールできます。

Scoopを使用する場合:

scoop install act

Chocolateyを使用する場合:

choco install act

Go言語からビルドする場合:

Go言語がインストールされている環境であれば、ソースコードからビルドすることも可能です。Go 1.20以上が必要です。

git clone https://github.com/nektos/act.git
cd act
make install

インストール後、act --version を実行して、正しくインストールされたか確認しましょう。

act --version

基本的な使い方

actの使い方は非常にシンプルです。まずは、最低限これだけ知っていれば使えるコマンドをいくつかご紹介します。

以下のワークフローファイル .github/workflows/main.yml を例として使用します。

# .github/workflows/main.yml
name: Local Workflow Test

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:
    inputs:
      greeting:
        description: 'Your greeting message'
        required: true
        default: 'Hello from workflow_dispatch!'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Say Hello
        run: echo "Hello, GitHub Actions!"
      - name: Show Current Directory
        run: pwd && ls -la
      - name: Use Secret
        env:
          MY_SECRET: ${{ secrets.MY_SECRET }}
        run: echo "My secret is: $MY_SECRET"
      - name: Check Input
        if: ${{ github.event_name == 'workflow_dispatch' }}
        run: echo "Input greeting: ${{ github.event.inputs.greeting }}"

  test:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Run Tests
        run: echo "Running tests..."

  deploy:
    runs-on: ubuntu-latest
    needs: test
    if: github.ref == 'refs/heads/main'
    steps:
      - name: Deploy to Staging
        run: echo "Deploying to staging..."

1. 実行可能なジョブの一覧表示

act が現在のディレクトリにあるワークフローファイルを認識し、どのジョブを実行できるかを確認します。

act --list
# または
act -l

このコマンドを実行すると、main.ymlで定義されたbuild、test、deployジョブが表示されます。

2. デフォルトイベントでのワークフロー実行

引数なしで act を実行すると、デフォルトのイベント（通常はpushイベント）でワークフロー全体を実行します。

act

初回実行時は、必要なDockerイメージのダウンロードやビルドが行われるため、時間がかかる場合があります。2回目以降はキャッシュが効くため高速です。

3. 特定のジョブのみを実行

ワークフロー内の特定のジョブだけをテストしたい場合、ジョブ名を指定して実行できます。

例えば、buildジョブのみを実行するには、次のように入力します。

act build

これにより、buildジョブとその依存関係（この例ではbuildのみ）が実行されます。

4. 特定のイベントタイプでワークフローを実行

GitHub Actionsは、push、pull_request、workflow_dispatchなど、様々なイベントによってトリガーされます。actもこれらのイベントをシミュレートできます。

例えば、pull_requestイベントとして実行するには、--eventオプションを使用します。

act --event pull_request

これにより、pull_requestイベントでトリガーされるジョブが実行されます。

5. シークレットを渡して実行

ワークフローで secrets を使用している場合、--secret または -s オプションでシークレットを渡す必要があります。

act -s MY_SECRET=my-super-secret-value

MY_SECRETという名前のシークレットにmy-super-secret-valueという値を渡します。複数のシークレットを渡すことも可能です。

便利な使い方・応用例 3選

actは基本的な使い方だけでなく、実際の開発シーンで役立つ多くの応用的な機能を持っています。

1. シークレットと環境変数の管理

シークレットは、認証情報やAPIキーなど、機密性の高い情報を扱うために不可欠です。actでは、これらのシークレットを安全に渡す方法が複数提供されています。

インラインでシークレットを渡す:

前述の通り、--secretオプションで直接値を渡せます。これは、一時的なテストや少数のシークレットの場合に便利です。

act -s GITHUB_TOKEN=ghp_exampletoken -s API_KEY=abcde12345

ファイルからシークレットを渡す:

より多くのシークレットを扱う場合や、機密情報をコマンドラインに残したくない場合は、ファイルからシークレットを読み込むのが良い方法です。 例えば、secrets.envというファイルを作成し、以下のように記述します。

# secrets.env
MY_SECRET=my-super-secret-value
GITHUB_TOKEN=ghp_exampletoken

このファイルを act に渡すには、--secret-file オプションを使用します。

act --secret-file secrets.env

これにより、ファイル内のすべてのシークレットがワークフローに提供されます。

2. 特定のイベントタイプと入力のシミュレーション

workflow_dispatchイベントは、手動でワークフローをトリガーし、その際にカスタムの入力値を受け取ることができます。actでは、このworkflow_dispatchイベントと入力値をローカルでシミュレートできます。

workflow_dispatchイベントのシミュレーション:

--eventオプションでworkflow_dispatchを指定し、--inputオプションで入力値を渡します。

act --event workflow_dispatch --input greeting='Hello from local act!'

上記のコマンドを実行すると、main.ymlのCheck Inputステップが実行され、「Input greeting: Hello from local act!」と出力されるはずです。

イベントペイロードファイルの利用:

より複雑なイベントペイロード（例えば pull_request イベントの詳細な情報）をシミュレートしたい場合は、JSONファイルを作成して渡すことができます。 例えば、my_event.jsonというファイルに以下のような内容を記述します。

{
  "pull_request": {
    "head": {
      "ref": "feature-branch"
    },
    "base": {
      "ref": "main"
    }
  }
}

そして、--event-fileオプションでこのファイルを指定します。

act --event pull_request --event-file my_event.json

これにより、指定したJSONの内容がgithub.eventコンテキストとしてワークフローに提供されます。

3. マトリックスビルドの実行とデバッグ

GitHub Actionsのマトリックスビルドは、複数の環境（OS、言語バージョンなど）でジョブを並行して実行する強力な機能です。actもこのマトリックスビルドをサポートしており、ローカルでのテストが可能です。

例えば、以下のワークフローがあるとします。

# .github/workflows/matrix-test.yml
name: Matrix Build Test

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [16, 18, 20]
        os: [ubuntu-latest, macos-latest]
    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js ${{ matrix.node-version }} on ${{ matrix.os }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
      - name: Show Node Version
        run: node -v
      - name: Show OS
        run: echo "Running on ${{ matrix.os }}"

このワークフローをactで実行すると、各マトリックスの組み合わせ（例: Node.js 16 on Ubuntu, Node.js 18 on Ubuntuなど）が個別のジョブとして実行されます。

act

actは、マトリックスの各組み合わせを独立したDockerコンテナで実行します。これにより、ローカル環境で複数の構成での動作を一度に確認できます。

ポート衝突の回避:

マトリックスビルドで、各ジョブが同じポートを使用するサービス（例えば、Webサーバーやデータベース）を起動する場合、ポート衝突が発生する可能性があります。 このような場合は、actの--container-architectureオプションや--privilegedオプションを調整するか、ワークフロー内で異なるポートを使用するように設定を調整する必要があります。 あるいは、docker-composeと組み合わせて、サービスごとに独立したネットワークを構成することも有効です。

他ツールとの組み合わせ

actは単体でも強力ですが、他のツールと組み合わせることで、さらに開発体験を向上させられます。

VS Code拡張機能「GitHub Local Actions」

Visual Studio Codeを使用している場合、「GitHub Local Actions」という拡張機能が非常に便利です。この拡張機能は act の機能をVS Codeに統合します。

エディタを離れることなく、ワークフローの実行、特定のジョブの実行、シークレットの管理など、actの主要な操作を行えます。これにより、GitHub Actionsの開発とデバッグがよりシームレスになります。

Docker Composeとの連携

GitHub Actionsのワークフローがデータベースやメッセージキューなど、外部サービスに依存する場合、それらのサービスもローカルで起動する必要があります。このようなケースでは、docker-composeが非常に役立ちます。

docker-compose.yml ファイルで必要なサービス（例: PostgreSQL、Redis）を定義し、actを実行する前にdocker-compose upでサービスを起動します。

例えば、docker-compose.ymlにPostgreSQLサービスを定義し、ワークフローでそのDBに接続するテストを行う場合です。

# docker-compose.yml
version: '3.8'
services:
  db:
    image: postgres:13
    environment:
      POSTGRES_DB: testdb
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    ports:
      - "5432:5432"

そして、actを実行する前に、別のターミナルでdocker-compose up -dを実行してデータベースを起動します。ワークフロー内では、dbサービスに接続するように設定します。

Makefileとの連携

actは、既存のMakefileの代替や補完として機能します。GitHub Actionsで定義したタスクを、ローカルの開発環境でもmakeコマンドのように実行できます。

例えば、Makefileにciターゲットを定義し、その中でactを呼び出すことで、ローカルでのCI実行をシンプルにできます。

# Makefile
.PHONY: ci

ci:
    @echo "Running GitHub Actions locally with act..."
    @act --container-architecture arm64 # M1 Macなどでアーキテクチャを指定

このように設定することで、make ciと入力するだけで、actがワークフローを実行します。

よくある設定・カスタマイズ

actは、~/.actrc ファイルやプロジェクトルートの .actrc ファイルを使って、デフォルトの動作をカスタマイズできます。

.actrc ファイルの活用

.actrcファイルは、コマンドラインオプションを事前に設定しておくためのものです。これにより、毎回長いオプションを入力する手間を省けます。

例えば、M1 MacなどのARMアーキテクチャの環境で、IntelベースのDockerイメージを使用する必要がある場合、--container-architectureオプションをよく使うかもしれません。

~/.actrc または プロジェクトルートの .actrc に以下のように記述します。

# .actrc
--container-architecture arm64
--secret-file secrets.env
--verbose

これで、actと実行するだけで、ARM64アーキテクチャのコンテナが使用され、secrets.envからシークレットが読み込まれ、詳細なログが表示されるようになります。

よく使用するオプションや、プロジェクト固有の設定を .actrc に記述しておくと便利です。

カスタムDockerイメージの利用

actはデフォルトで、GitHub Actionsが提供する仮想環境と互換性のあるDockerイメージを使用します。しかし、特定のツールや環境が必要な場合、独自のDockerイメージを作成して使用することも可能です。

ワークフロー内でruns-on: ubuntu-latestではなく、カスタムイメージを指定することはできませんが、actの実行時に--platformオプションでDockerプラットフォームを指定できます。 また、actはワークフロー内でuses: docker://...と指定されたDockerアクションも実行できます。

より高度なカスタマイズとしては、act自体が使用するベースイメージを.actrcで指定するオプションも検討できますが、通常はデフォルトのイメージで十分です。

今日からできる実行プラン

actをあなたの開発ワークフローに組み込むのは非常に簡単です。以下の3つのステップで、今日からactを使い始めましょう。

ステップ1: actをインストールする

まずは、あなたの開発環境にactをインストールします。前述の「インストール方法」セクションを参考に、お使いのOSに合った方法でインストールしてください。

# 例えばmacOSの場合
brew install act

インストールが完了したら、act --versionを実行して、正しくインストールされたことを確認しましょう。

ステップ2: 既存のGitHub Actionsワークフローをローカルで実行してみる

次に、既存のGitHub Actionsワークフローがあるリポジトリに移動し、actを試してみます。

リポジトリのルートディレクトリで以下のコマンドを実行してください。

act

初回実行時はDockerイメージのダウンロードに時間がかかる場合がありますが、しばらく待つとワークフローがローカルで実行され、そのログがターミナルに表示されます。エラーが発生した場合は、その場で修正し、再度actを実行して確認できます。

シークレットが必要なワークフローの場合は、--secretオプションや--secret-fileオプションを試してみてください。

act -s GITHUB_TOKEN=your_local_token

ステップ3: 新しいワークフローの開発やデバッグにactを活用する

actの基本的な使い方に慣れたら、新しいGitHub Actionsワークフローを作成する際や、既存のワークフローで発生した問題をデバッグする際に積極的に活用しましょう。

• 新しいワークフローの設計: まずローカルでactを使って試行錯誤し、動作が確認できてからリモートリポジトリにプッシュします。
• デバッグ: リモートでCIが失敗した場合、そのワークフローをactでローカル実行し、詳細なログを確認しながら問題を特定・修正します。

actを日常的に使うことで、「プッシュ・アンド・待つ」のサイクルから解放され、GitHub Actionsの開発効率が飛躍的に向上するはずです。

参考文献

• Run and debug GitHub Actions locally via Docker with nektos/act
• Running Local GitHub Actions with Nektos Act
• Skip the Push: How to Debug GitHub Actions Locally Using Nektos/Act
• Develop GitHub actions faster with 'act', an easy example
• Run GitHub Actions locally with DinD and nektos/act
• nektos/act GitHubリポジトリ
• act user guide