AI 記事

GitHub Actionsのデバッグが爆速に！actでCI/CD開発を劇的に変える実践ガイド

GitHub Actionsのデバッグが爆速に！actでCI/CD開発を劇的に変える実践ガイド

CI/CDワークフローのデバッグに、時間とコストを無駄にしていませんか？ GitHub Actionsの小さな変更でも、コミット・プッシュ・クラウド実行を繰り返すのは、開発者の大きな負担です。1回の試行に数分かかる作業を、何度も繰り返すのは避けたいはずです。

このサイクルをローカル環境で瞬時に実行できるツール「act」を使えば、あなたのCI/CD開発は劇的に変わります。クラウド利用料を抑え、デバッグ時間を90%短縮する実践的な方法を紹介します。

GitHub Actionsの「試行錯誤コスト」を理解する

CI/CDワークフローの開発は、時に厄介なものです。特にGitHub Actionsの場合、開発者は次の課題に直面しがちです。

  • クラウドでの実行待ち時間: ワークフローの小さな変更でも、コミットし、GitHubにプッシュし、GitHub Actionsランナーが起動するまで数分待つ必要があります。この待ち時間は1回あたり3分から5分程度かかる場合があります。
  • 利用料の発生: パブリックリポジトリ以外では、GitHub Actionsの実行には料金が発生します。デバッグのために何度も実行すると、利用料が無駄にかさんでしまいます。
  • 状態再現の難しさ: クラウド環境でのみ発生する問題もありますが、多くの場合、ローカル環境で再現できる問題です。しかし、デバッグはクラウド上で行うため、ログを追うのに手間がかかります。

例えば、新しいテストステップを追加したとします。そのテストスクリプトにタイプミスがあった場合、クラウドで実行して初めてエラーが発覚します。修正し、再度コミット・プッシュ。この繰り返しで、1つのエラー解決に30分以上かかることも珍しくありません。

actとは？ローカル実行でCI/CD開発が変わる

actは、GitHub Actionsワークフローをローカル環境で実行するためのコマンドラインツールです。Dockerコンテナを利用して、GitHub Actionsの実行環境を再現します。

このツールの最大のメリットは、高速フィードバックサイクルです。クラウドにプッシュする手間なく、手元のPCでワークフローの動作をすぐに確認できます。「Think globally, act locally（グローバルに考え、ローカルで実行する）」というactの哲学は、まさに開発者の悩みに応えるものです。

actを使うと、次の2つの点でCI/CD開発が大きく改善します。

  1. 高速フィードバック: .github/workflows/ ファイルの変更や、埋め込まれたGitHubアクションの変更をテストする際、コミット・プッシュの繰り返しは不要です。actを使えばローカルで即座に実行できます。GitHubが提供する環境変数やファイルシステムも忠実に再現します。
  2. ローカルタスクランナー: Makefileのようなタスクランナーの代わりに、actを導入できます。.github/workflows/ に定義したGitHub Actionsを、そのままローカルのタスク実行に利用できます。

actのインストールと初期設定

actを使うには、DockerがPCにインストールされ、実行されている必要があります。まだ導入していない場合は、事前にDocker Desktopなどをインストールしてください。

actのインストール方法は、お使いのOSによって異なります。

macOSの場合

Homebrewを使って簡単にインストールできます。

brew install act

Windowsの場合

Scoopを使ってインストールします。

scoop install act

Linuxの場合

aptなどのパッケージマネージャで提供されている場合もあります。公式のリリースページからバイナリをダウンロードして手動でインストールすることも可能です。

# 例: curlとtarでインストール (Linuxの場合)
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | bash

初期設定

actを初めて実行する際、デフォルトのDockerイメージを選択するよう求められます。これは、GitHub Actionsが提供する仮想環境の種類に対応します。

act --init

--init コマンドを実行すると、ワークフローの実行に使うDockerイメージの候補が表示されます。軽量な「micro」イメージを選ぶと、ダウンロードサイズが小さく、起動も素早いです。

? Choose the default image you want to use for running actions: [Use arrows to move, type to filter]
>  [Micro] act_micro/ubuntu:20.04 (< 100MB)
   [Small] catthehacker/ubuntu:act-20.04 (≈ 500MB)
   [Medium] ghcr.io/catthehacker/ubuntu:act-latest (≈ 2GB)

通常は [Micro] を選択すれば問題ありません。

具体的なデバッグ実践ワークフロー

新しい機能開発で、CI/CDワークフローにテストステップを追加するシーンを考えます。開発者は、プロジェクトの依存関係をインストールし、単体テストを実行するステップを test.yml に追加しました。

# .github/workflows/test.yml
name: My Test Workflow
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Set up Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '20'
    - name: Install dependencies
      run: npm install
    - name: Run tests
      run: npm test # ここに問題がある可能性

このワークフローをコミットしてプッシュしたところ、npm test ステップでエラーが発生しました。しかし、エラーメッセージだけでは原因が特定しにくい状況です。

actを使った解決ワークフロー

  1. ワークフローを一覧表示: まず、actが認識しているワークフローのジョブを確認します。

    act --list

    このコマンドで、My Test Workflow の build ジョブがリストされます。

  2. 特定のジョブを実行: npm test のエラーをデバッグするため、build ジョブだけをローカルで実行します。

    act -j build

    actはDockerコンテナ内でワークフローを実行し、コンソールに詳細なログを出力します。クラウドでの実行結果とほぼ同じログが得られます。このログをじっくり確認すると、「package.json に test スクリプトが定義されていない」という具体的なエラーメッセージが見つかりました。

  3. ワークフローを修正し、再実行: package.json に test スクリプトを追加し、再度 act -j build を実行します。今度はエラーなく完了しました。

    // package.json
{
  "name": "my-app",
  "version": "1.0.0",
  "scripts": {
    "test": "jest" // これを追加
  },
  "devDependencies": {
    "jest": "^29.0.0"
  }
}

    ローカルでの試行錯誤は数秒で完了します。クラウドでの実行を待つ必要は全くありません。

  4. ドライランで実行計画を確認: 大規模なワークフローや複雑なステップの場合、実際に実行する前に、どのようなステップが実行されるか確認したいことがあります。--dry-run オプションを使うと、実行計画を詳細に表示できます。

    act --dry-run

    このコマンドは、環境変数の設定やアクションのダウンロードなど、実行される全てのステップをリストアップします。実際にコンテナを起動しないため、安全にワークフローの構成を確認できます。

この体験から読者が学べること: actを使うことで、GitHub Actionsのデバッグサイクルを大幅に短縮できます。クラウドでの待ち時間や利用料を気にせず、ローカルで素早くエラーを発見し、修正できます。

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

  • 既存のGitHub Actionsワークフローをローカルで act を使って実行してみる。
  • act -j [ジョブ名] で特定のジョブだけをデバッグする習慣をつける。
  • 新しいワークフローを開発する際、まず act でローカル検証するプロセスを取り入れる。

actをさらに活用するヒント

actには、より高度な利用を可能にする便利な機能が多数あります。

  • VS Code拡張機能: Visual Studio Codeを使っているなら、「GitHub Local Actions」拡張機能がおすすめです。エディタ内で actの機能を利用でき、ワークフローの実行やテストがより直感的に行えます。

  • シークレットの扱い: GitHub Actionsのシークレットは、ローカルでは .env ファイルに記述することで扱えます。

    # .envファイルを作成
# GITHUB_TOKEN=your_token_here
# MY_SECRET=my_secret_value

    actを実行する際、これらの変数が自動的に読み込まれます。特定のシークレットだけを渡したい場合は --secret オプションも利用できます。

    act -s MY_SECRET=my_value

  • プライベートリポジトリからのアクション利用: プライベートリポジトリにあるアクションを使いたい場合、actはGitHub APIへのアクセスが必要です。--token オプションでGitHub Personal Access Tokenを渡すことで、プライベートアクションも利用できます。

    act --token your_github_pat

これらの機能を活用すれば、より本番に近い環境でワークフローをデバッグし、開発効率をさらに高められます。

締め

GitHub Actionsのデバッグは、もうクラウドでの試行錯誤の繰り返しではありません。actを活用すれば、ローカル環境でワークフローを高速に実行し、問題を瞬時に特定し、修正できます。開発効率を大幅に向上させ、無駄なクラウド利用料も節約できるこのツールを、ぜひあなたの開発ワークフローに取り入れてください。

参考文献

まとめ・次のステップ

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

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

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

広告

-AI, 記事