なぜCIは「夜中に」壊れるのか？GitHub Actionsのデバッグを極め、開発速度を10倍にする技術
「ローカルでは動いたのに、CIでは落ちる」。このエンジニア界の悪夢に、我々はいつまで時間を浪費するつもりだろうか。
GitHub Actionsは強力だが、ブラックボックス化しやすい。ログを眺めて「retry」ボタンを連打するのは、運任せのギャンブルだ。真のテックリードは、「再現」と「可視化」を支配する。
今日は、CIのトラブルシューティングを「神域」へと引き上げるための、現場で使える極限の知見を授ける。
—
1. ログの向こう側を見る：`ACTIONS_STEP_DEBUG`の真価
標準的なログでは詳細が足りない時、迷わず`ACTIONS_STEP_DEBUG`を使え。
GitHub Secretsに `ACTIONS_STEP_DEBUG` = `true` を設定するだけで、 runnerの内部挙動が詳細に吐き出される。
- 何が見えるか: APIのレスポンスヘッダー、環境変数の展開過程、runner内でのシェル実行の逐次ログ。
- 注意点: 機密情報が漏洩する可能性があるため、本番環境のSecretを扱うジョブでは使用を控え、デバッグ用のブランチやPRでのみ有効化せよ。
2. 「ローカル再現」こそが最強の武器：actの活用
CIを待つ時間は無駄だ。`act`を使えば、GitHub ActionsのワークフローをローカルのDockerコンテナ上で実行できる。
特定のジョブのみ、ローカルでDockerコンテナを立ち上げて実行
act -j build-and-test –container-architecture linux/amd64
【プロの活用術】
失敗したステップの直前で `sleep 3600` を挿入し、CIをわざと待機させ、コンテナに `docker exec` で潜り込む手法も有効だ。環境変数やディレクトリ構造が「生」の状態で確認できるため、迷宮入りしたバグも一瞬で特定できる。
3. YAMLの地獄を回避する：ベストプラクティス構成
GitHub ActionsのYAMLは、肥大化すると保守不能になる。以下のルールをチームの憲法にせよ。
- LogicをShellに逃がす: YAML内に長大な `run` を書くな。`./scripts/ci/test.sh` のように、シェルスクリプトをリポジトリ内に管理せよ。これにより、ローカルでのテストが容易になる。
- Composite Actionsの活用: 頻出するセットアップ手順（認証、ツールインストール、キャッシュ設定）は、`action.yml` に切り出して共通化せよ。
理想的なディレクトリ構成
.github/
workflows/
ci.yml # ワークフロー定義（宣言的に記述）
actions/
setup-env/ # 再利用可能なComposite Action
action.yml
scripts/
ci/
run-tests.sh # 実行ロジックはここへ
4. 開発速度を劇的に高める「神ツール・設定」
ツールを知る者は、環境を支配する。
- GitHub CLI (`gh`): CIの状況確認のためにブラウザを開く必要はない。
- `gh run watch` : 実行中のCIをターミナルで追跡。
- `gh run view –log` : 失敗したログを直接ターミナルに表示。
- VS Code拡張機能 “GitHub Actions”:
- YAMLの補完だけでなく、ワークフローの実行状態をステータスバーで監視できる。CIが落ちた瞬間に通知が来る設定にしておけば、修正の初動が数分早まる。
5. チーム開発における「CI破綻」を防ぐルール
CIは「壊れたら即座に、誰が直すべきか明白である」状態を目指すべきだ。
1. Fail-Fast戦略: `fail-fast: true` を設定し、1つのマトリクスが落ちた瞬間に全てを停止させろ。無駄なリソース消費とログのノイズを排除する。
2. キャッシュ戦略の徹底: `actions/cache` を使う際は、keyに `hashFiles(‘/package-lock.json’)` を必ず含めよ。キャッシュの不整合による謎のエラーを根絶する。
3. OWNERSファイルの活用: `CODEOWNERS` を設定し、CIの修正が必要な時に誰をメンションすべきか自動で定義しておけ。
—
最後に：テックリードからの提言
CIのトラブルは、多くの場合「環境の差異」と「仕様の甘え」に起因する。
GitHub Actionsを単なる「自動実行機」と捉えるな。「再現可能なテスト環境を構築するエンジニアリング」そのものだと考えろ。
ログを見て溜息をつく時間は終わりだ。`act`を導入し、スクリプトを疎結合にし、コマンドラインからすべてを制御する。その環境こそが、君のチームを「世界最高峰」へと押し上げる。
さあ、次はどのワークフローを最適化する？