AI 記事

GitHub Actionsを爆速デバッグ！actでローカル実行

GitHub Actionsを爆速デバッグ！actでローカル実行

新しい機能を追加したとき、GitHub Actionsのワークフローが動かずに困った経験はありませんか？変更をプッシュするたび、リモートでの実行を待ち、失敗を確認しては修正する。この繰り返しは、開発の大きなボトルネックです。1回の実行に5分以上かかることもあります。

この「待ち時間」が積もり積もると、1日あたり30分以上の無駄な時間になりかねません。しかし、この非効率なデバッグプロセスを劇的に改善するツールがあります。それが act です。

act を使えば、GitHub Actionsのワークフローをローカル環境で実行できます。これにより、リモートへのプッシュなしで、瞬時にデバッグサイクルを回せます。開発時間を短縮し、ストレスなくCI/CDを構築できるのです。

GitHub Actionsの「待ち時間」が開発を遅らせる

ソフトウェア開発では、CI/CD（継続的インテグレーション・継続的デリバリー）が欠かせません。GitHub Actionsはその強力なツールの一つです。しかし、ワークフローの作成や修正には特有の課題があります。

特に、デバッグのプロセスです。新しいワークフローを試すたび、コードをGitHubへプッシュします。その後、GitHubのサーバーでワークフローが実行されるのを待たねばなりません。

このフィードバックループは、平均で3〜10分かかります。小さなミスでも、プッシュと待ち時間を繰り返す必要があり、開発効率は大きく低下します。ワークフローが複雑になるほど、この待ち時間は無視できない問題となるでしょう。

act とは何か？ローカル実行のメリットを理解する

act は、GitHub Actionsのワークフローをローカル環境で実行するコマンドラインツールです。開発元はnektosというオープンソースプロジェクトです。

このツールが提供する最大のメリットは、高速なフィードバックです。リモートにプッシュせず、手元のマシンでワークフローを動かせます。これにより、変更を即座に確認し、デバッグ時間を大幅に短縮できます。

act はDockerコンテナを利用してワークフローを実行します。そのため、GitHubが提供するランナー環境にかなり近い状態を再現できます。環境変数やファイルシステムも、GitHub Actionsの仕様に合わせて設定されます。

また、act をローカルのタスクランナーとして使う方法もあります。ワークフローファイルを Makefile のように活用し、普段のタスクを自動化することも可能です。

act を動かす準備：Dockerとツールのインストール手順

act を使うには、まずDocker環境が必要です。Docker Desktopなどを事前にインストールしてください。

  • Docker Desktop公式ダウンロードページ

Dockerの準備ができたら、act をインストールします。macOSならHomebrewを使うのが簡単です。

brew install act

Linux環境では、curl を使ってインストールスクリプトを実行します。

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

Windowsの場合は、WSL2環境でLinuxのインストール方法を使うか、Scoopなどのパッケージマネージャーを利用できます。

インストール後、act --version を実行してバージョン情報が表示されれば準備完了です。

act --version

実際のワークフローをローカルで動かす基本コマンド

act のインストールが済んだら、さっそく既存のGitHub Actionsワークフローを動かしてみましょう。

まず、./.github/workflows/ ディレクトリに、以下のようなシンプルなワークフローファイル main.yml を作成します。

# ./.github/workflows/main.yml
name: Simple Workflow

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Run a one-line script
        run: echo "Hello, GitHub Actions Local!"

      - name: Show current directory
        run: pwd

      - name: List files
        run: ls -la

このワークフローは、リポジトリをチェックアウトし、メッセージを表示するものです。次に、コマンドラインでプロジェクトのルートディレクトリに移動します。

act の実行は非常にシンプルです。

act

初回実行時には、act が必要なDockerイメージをダウンロードします。少し時間がかかるかもしれませんが、2回目以降は高速です。

実行が開始されると、ターミナルにワークフローのログが流れていきます。echo "Hello, GitHub Actions Local!" の出力が確認できれば成功です。

特定のイベント（push や pull_request など）を指定して実行することも可能です。main.yml は on: [push] なので、push イベントを明示して実行できます。

act push

また、ワークフロー内の特定のジョブだけを実行したい場合は、-j オプションを使います。上記の例では build ジョブです。

act -j build

これにより、必要な部分だけをテストし、デバッグ時間をさらに短縮できます。

デバッグ効率を上げる act の実践テクニック

act には、デバッグ効率を高めるための便利なオプションが多数用意されています。

1. ログレベルを調整する

デフォルトでは、act は詳細なログを出力します。ログが多くて読みにくい場合、-v や -q オプションでログレベルを調整できます。

  • -v (verbose): より詳細なログを出力します。
  • -q (quiet): 重要な情報のみ表示し、ログを最小限に抑えます。
act -q push

2. 環境変数やシークレットを設定する

GitHub Actionsのワークフローでは、環境変数やシークレットが頻繁に使われます。act でもこれらをローカルで設定できます。

環境変数は -e オプション、シークレットは -s オプションで渡します。

# 環境変数を設定
act -e MY_ENV_VAR=my_value

# シークレットを設定
act -s MY_SECRET=my_secret_value

# 環境変数とシークレットの両方を設定
act -e MY_ENV_VAR=my_value -s MY_SECRET=my_secret_value

また、.env ファイルや .secrets ファイルを使って、まとめて設定することも可能です。

  • .env ファイルの例:
    MY_ENV_VAR=my_value
ANOTHER_ENV=another_value
  • .secrets ファイルの例:
    MY_SECRET=my_secret_value
API_KEY=your_api_key

ファイルを作成したら、act コマンドは自動的にこれらを読み込みます。

3. 特定のGitHub Actionsイベントのペイロードをシミュレートする

act は、GitHub ActionsのイベントペイロードをJSONファイルで指定することも可能です。これにより、プルリクエストや 이슈作成など、特定のイベント発生時のワークフロー動作を細かくテストできます。

例えば、pull_request イベントをシミュレートする場合、まずGitHubのドキュメントや既存のワークフロー実行ログからペイロードのJSONを取得します。それを payload.json として保存します。

act pull_request --eventpath payload.json

この機能は、複雑なイベントトリガーを持つワークフローのデバッグに非常に有効です。

ある開発者の体験：CI/CDデバッグが劇的に変わった話

副業でSaaS開発に取り組むある開発者は、以前、新しいCI/CDワークフローの構築に大きな課題を感じていました。特に、デプロイ関連のワークフローは複雑で、少しの変更でも失敗することが頻繁にあったのです。

この開発者は、1日に平均で5〜7回、GitHubにコードをプッシュし直していました。1回のワークフロー実行と確認には、平均7分かかります。合計すると、1日あたり最低でも35分以上をデバッグの「待ち時間」に費やしていた計算です。

この遅いフィードバックループが原因で、開発のモチベーションも低下していました。

ある時、この開発者は act の存在を知り、導入を決意しました。Docker環境は既に構築済みだったため、brew install act ですぐに使い始められました。

act を使い始めてからの変化は劇的でした。まず、ワークフローの変更後、リモートへプッシュする前にローカルで実行できるようになりました。1回あたりの実行時間は平均10秒に短縮されました。

これにより、プッシュ回数は1日に1〜2回に激減。デバッグにかかる総時間は、1日あたり5分以下に収まるようになりました。以前は35分以上かかっていたデバッグが、約7分の1に短縮されたのです。

この体験から読者が学べること: act はCI/CDワークフローのデバッグサイクルを大幅に短縮し、開発者のストレスを減らします。

今日から実行できるアクションプラン:

  • act をインストールし、手元の開発環境で使えるようにする。
  • 既存のGitHub Actionsワークフローを act でローカル実行してみる。
  • 失敗した際に、リモートへプッシュする前に act でローカルデバッグする習慣をつける。

今日から始める act 活用プラン

GitHub Actionsのデバッグは、これまでの「待ち」のプロセスから、「即座に確認」できるプロセスへと進化しました。act は、その変化を実現する強力なツールです。

今日から act を導入し、GitHub Actionsのデバッグ体験を変えましょう。高速なフィードバックサイクルを手に入れ、より効率的でストレスフリーな開発を実現してください。

参考文献

まとめ・次のステップ

この記事が役に立ったら、ブログのメールマガジンへ登録してください。 AI活用・個人開発・副業に関する最新情報を週1回お届けします。

👉 無料メルマガに登録する（Waitlist）

このブログでは、会社員をしながら副業でSaaSを開発する過程をリアルに発信しています。使用スタック: Next.js / Supabase / Claude API / Vercel

広告

-AI, 記事