こんにちは。DevOpsの世界へようこそ。
GitHub Actionsを使い始めると、誰もが一度は直面する壁があります。それは「ローカルでは動くのに、なぜかCIでだけコケる」という怪奇現象です。
エラーログを眺めて「また失敗した…」と溜息をつくのはもう終わりにしましょう。CI/CDの真髄は「自動化」ではなく「失敗をいかに速く、正確に特定するか」にあります。今日は、GitHub Actionsで発生する不可解なトラブルを外科手術のように解決するための、プロのデバッグ作法を伝授します。
—
1. GitHub Actionsの「ログ」は単なる文字の羅列ではない
CIが失敗したとき、皆さんはどうしていますか？ ログの最後を眺めて、「あー、またコマンドが見つからないって言ってるな」と確認するだけでは不十分です。
GitHub Actionsのログには、実行環境のメタデータが隠されています。
- 環境変数の確認: ログの冒頭には、そのステップで有効な環境変数が一覧表示されています。シークレットが正しく注入されているか、`GITHUB_SHA`や`GITHUB_REF`が意図した値か、まずはここを疑ってください。
- タイムスタンプの相関: ステップとステップの間の「空白時間」に注目してください。ここで時間がかかっているなら、ネットワーク待ちや、不要なパッケージのインストールが発生している証拠です。
2. 「ACTIONS_STEP_DEBUG」という最強の武器
どうしても原因が特定できないとき、魔法の呪文があります。リポジトリの「Secrets」設定に、以下のキーと値を追加してください。
- Key: `ACTIONS_STEP_DEBUG`
- Value: `true`
これを設定するだけで、GitHub Actionsのログに「Runnerが裏側で何をやっているか」という詳細なデバッグ情報が溢れ出します。APIのレスポンスや、内部的なコマンド実行の様子が手に取るようにわかるようになります。
注意: 非常に詳細なログが出るため、解決したら必ず削除してくださいね。
3. ローカルで再現する：actの活用
「CIを回すたびにコミットしてPushするのはもう無理！」という方に。ローカル環境でGitHub Actionsをシミュレートするツール、[nektos/act](https://github.com/nektos/act) を導入しましょう。
インストール方法（Macの場合）:
brew install act
使い方:
プロジェクトのルートで以下のコマンドを叩くだけです。
特定のジョブだけをローカルで実行
act -j <ジョブ名>
これで、GitHubのサーバーに頼らず、Dockerコンテナ上でCIを回せます。「Pushしてから失敗を確認」という遅いフィードバックループから完全に解放されます。
4. 精度高い「HelloWorld」的デバッグ・ワークフロー
まずは、GitHub Actionsの挙動を完全に把握するための「診断用ワークフロー」を用意しましょう。`.github/workflows/debug.yml`として作成してみてください。
name: Debugging Toolkit
on: workflow_dispatch # 手動でいつでも実行可能にする
jobs:
diagnose:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Inspect Environment # 環境変数をすべてダンプする
run: |
echo “現在の環境変数は以下の通りです：”
env | sort # 環境変数をアルファベット順に表示
- name: List Directory # ファイル構成を確認する
run: |
echo “カレントディレクトリの構成：”
ls -R
このワークフローのポイント:
- `workflow_dispatch` を使うことで、メインブランチにマージしなくても、GitHub UI上の「Run workflow」ボタンからいつでもテスト実行できます。
- `env | sort` で、現在のRunnerがどんな設定を持っているか丸裸にします。
5. 失敗しないための「プロの心得」
最後に、トラブルを未然に防ぐための3つの鉄則を授けます。
1. パス依存を避ける: `ls`で確認するまでもなく、`pwd`や`GITHUB_WORKSPACE`を絶対パスで意識する癖をつけてください。
2. 冪等性（べきとうせい）を担保する: 「何度実行しても同じ結果になる」状態を維持してください。キャッシュの削除やクリーンアップを意識するだけで、CIの失敗は半分に減ります。
3. ステップは小さく刻む: 1つのステップで何でもやらせないこと。失敗した場所が「どこか」を一目でわかるようにする。これが保守性の極意です。
—
終わりに：ツールを使いこなす楽しさ
GitHub Actionsのデバッグは、パズルに似ています。ログという手がかりを頼りに、Runnerの脳内を覗き込み、正解を導き出す。このプロセスを楽しめるようになれば、あなたはもう初心者ではありません。
最初は「なぜ？」の連続かもしれませんが、その苦労こそが、あなたのエンジニアとしての武器になります。
「これをマスターすれば、毎日の作業が劇的に楽になりますよ」。
さあ、今すぐ自分のプロジェクトで `workflow_dispatch` を試してみてください。昨日まで冷たかったCIが、あなたの頼もしいパートナーに変わる瞬間を体験できるはずです。
応援しています！