Posted inDocker

actでGitHub Actionsをローカル実行：コードをプッシュせずにパイプラインを「超速」デバッグ

Docker tutorial - IT technology blog
Docker tutorial - IT technology blog

午前2時の「Fix CI/CD」という悪夢

このシナリオは、エンジニアなら誰しも経験があるはずです。深夜に本番環境がダウン。急いでコードを修正してプッシュし、GitHub Actionsが成功することを祈りながら待ちます。しかし、無情にも回転するアイコンの後に現れるのは真っ赤な「X」マーク。エラーの原因はコードのロジックではなく、YAMLファイルのスペースが1つ多かったり、環境変数が1つ足りなかったりといった些細なことです。

ここから暗黒の時間が始まります。YAMLを修正し、コードをプッシュし、Runnerが起動するまで3〜5分待つ。またエラー。また修正、またプッシュ。2時間の格闘の末、Git의履歴は「fix ci」、「fix ci again」、「hope this works」といった20個ものコミットが並ぶ戦場のようになります。時間の無駄なだけでなく、非常にストレスが溜まります！

なぜGitHub Actions의デバッグはこれほど大変なのか？

クラウドCI/CD의最大の「痛み」は、フィードバックループ（反応의サイクル）が遅すぎることです。どんなに小さな変更でも、GitHubサーバーにコードをプッシュしなければなりません。GitHub의コンテナ内部で何が起きているのかは、手動で ls -la や echo $VAR を大量に挿入してログを丹念に確認しない限り、全く見えません。

私はかつて、実行権限の設定を忘れたために、たった一行の chmod +x deploy.sh を修正してプッシュし直す作業を繰り返し、午前中を丸々潰したことがあります。同僚は私のコミット履歴を見て、呆れて首を振るばかりでした。もしその時、自分のPCでワークフローを実行する方法を知っていれば、少なくとも3時間の作業時間と、GitHub Actionsの貴重な無料枠を節約できていたはずです。

これまでの暫定的な解決策（とその欠点）

  • スクリプトを手動で実行： YAMLのコマンドをローカルのターミナルにコピーして実行します。結果は？自分のPCはmacOSやWindowsで、RunnerはUbuntuです。Nodeのバージョン違いやシステムライブラリの不足により、GitHubに上げると結局エラーになります。
  • テスト用の使い捨てブランチを使用： メインブランチを汚さないようにはできますが、依然としてRunnerの起動を待つ必要があります。引用符が1つ抜けていたことを知るために5分待つのは、本当に「辛い」ものです。

救世主の登場：「act」でGitHub Actionsをローカルに持ち込む

この無駄を終わらせるために、act を使いましょう。このツールはDockerを使用して、GitHub Runnerとほぼ同一のシミュレーション環境をローカルに構築します。ワークフローファイルを読み込み、自動的にイメージをダウンロードして、一瞬でジョブを実行します。

30秒で完了するactのインストール

act のインストールは非常に簡単です。OSに合わせて以下のコマンドを使用してください：

# macOS (Homebrew)
brew install nektos/tap/act

# Windows (Winget)
winget install nektos.act

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

注意：act がジョブを実行するための基盤として Dockerがインストールされていること が必須です。

最初のワークフローを実行する

プロジェクトのルートディレクトリ（.github/ フォルダがある場所）に移動して、以下を入力するだけです：

act

デフォルトでは、このコマンドは push イベントに対応するジョブを実行します。他のイベントを実行したり、特定のジョブを指定したりするには、以下を使用します：

# pull_request イベントを実行
act pull_request

# 実行可能なジョブの一覧を表示
act -l

# 'build-test' という名前のジョブのみを実行
act -j build-test

Secretsの管理も心配無用

GitHubのウェブ画面でSecretsを設定する代わりに、ローカルに .env ファイルを作成して指定するだけです：

act --secret-file .env

.env ファイルの内容はお馴染みの形式です：

DOCKER_PASSWORD=my_secret_key
AWS_ACCESS_KEY_ID=AKIAXXXXXXXXXXXX

重要：誤ってシークレットをリポジトリにプッシュしてしまわないよう、必ず .env を .gitignore に追加してください。

actを効果的に使いこなすための「鉄則」

強力なツールですが、act は実際のクラウド環境とは異なる点があります。以下の3点に注意してください：

1. 巨大なイメージを避け、適切なものを選択する

初回実行時に、act はイメージの選択（Small, Medium, Large）を求めます。GitHubのデフォルトイメージは15GB以上もあります。ディスク容量に余裕がない場合は、Medium（約500MB）を選択しましょう。Smallは git や curl が不足していることが多く、YAMLの間違いだと勘違いしてしまうような些細なエラーの原因になります。

2. Docker-in-Dockerの扱い

ワークフロー内に docker build コマンドがある場合、ホストマシンのDockerソケットを act のコンテナと共有する必要があります。その際は以下のフラグを使用します：

act --container-daemon-socket /var/run/docker.sock

3. アーティファクト（Artifacts）の確認

act はビルドファイル（アーティファクト）を自動的にクラウドへアップロードしません。実行後の成果物を確認するには、--artifact-server-path を使用して、ローカルの指定したフォルダにファイルを直接保存するようにします。

結論：CI/CDに振り回されるのではなく、使いこなそう

act を使うことは、単なる時間の節約ではありません。素早くテストし、早期に失敗を見つけ、その場で修正するというプロフェッショナルなDevOpsの思考を養うことができます。単純な構文エラーで睡眠時間を削ったり、Gitの履歴を「fix ci」の山にしたりするのはもうやめましょう。

今日から act を試してみてください。CI/CDのデバッグも、コードを書くのと同じくらい楽しくなるはずです！

Share:
Tags: