Github Actions Debugging

GitHub Actions Debugging Skill

概要

GitHub Actionsワークフロー実行時のエラー診断、デバッグログ有効化、環境トラブルシューティングを体系的に実施します。

ワークフロー

Phase 1: エラー特定

目的: ワークフローログから失敗の根本原因を特定する

Task: agents/error-identification.md

アクション:

1. ワークフローログまたは実行IDを取得
2. scripts/analyze-logs.mjs でログを分析
3. references/troubleshooting-guide.md でエラーパターンをマッチング
4. エラー診断レポートを生成

次のフェーズ: エラーカテゴリに応じて Phase 2, 3, または 4 へ

Phase 2: デバッグログ有効化

目的: 詳細なデバッグログを収集できる状態にする

Task: agents/debug-enablement.md

アクション:

1. エラー診断レポートからデバッグレベルを判断
2. references/debug-logging.md で設定方法を確認
3. リポジトリシークレット設定手順を生成
4. ワークフロー再実行とクリーンアップ手順を提供

次のフェーズ: 再実行後、Phase 1 に戻る

Phase 3: コンテキスト検査

目的: GitHub Actionsの実行コンテキストから問題を特定する

Task: agents/context-inspection.md

アクション:

1. 必要なコンテキストオブジェクト（github、env、runner等）を決定
2. references/diagnostic-commands.md でコンテキスト検査コマンドを確認
3. コンテキストダンプ用のワークフロー修正案を生成
4. コンテキスト情報を分析してレポート作成

次のフェーズ: 環境問題が疑われる場合 Phase 4 へ

Phase 4: 環境診断

目的: ランナー環境のリソースとツールを診断する

Task: agents/environment-diagnosis.md

アクション:

1. 診断対象（ディスク、メモリ、ツールバージョン等）を決定
2. references/diagnostic-commands.md で診断コマンドを確認
3. 環境診断用ワークフローステップを生成
4. 環境情報を分析して解決策を提供

次のフェーズ: 解決策実装後、Phase 1 で検証

Task仕様（ナビゲーション）

各Taskは agents/ ディレクトリに配置されています。実行直前に該当するTaskファイルを読み込んでください。

リソース参照

references/（知識外部化）

スクリプト（scripts/）

• scripts/analyze-logs.mjs: ワークフローログ分析スクリプト
  • 引数: <log-file-path>
  • 出力: エラーパターン、失敗ステップ、推奨アクション
  • 失敗時: ログファイルパスの確認、ファイル形式の検証
• scripts/log_usage.mjs: 使用記録・自動評価スクリプト
  • 引数: --result <success|failure> [--phase <phase-name>] [--notes <notes>]
  • 出力: LOGS.mdへの記録、EVALS.jsonの更新
• scripts/validate-skill.mjs: スキル構造検証スクリプト
  • 引数: なし
  • 出力: 構造検証結果、エラー一覧

テンプレート（assets/）

• assets/debug-workflow.yaml: デバッグログ有効化ワークフローテンプレート

ベストプラクティス

すべきこと

• Phase 1（エラー特定）から開始し、体系的に診断を進める
• scripts/analyze-logs.mjs を活用してログ分析を効率化する
• デバッグログは段階的に有効化（STEP_DEBUG → RUNNER_DEBUG）
• コンテキスト検査では secrets コンテキストをダンプしない
• デバッグ完了後はシークレットを削除する

避けるべきこと

• ログの手動分析から始める（スクリプトを優先）
• すべてのデバッグログを一度に有効化する（段階的アプローチ）
• センシティブ情報を含むコンテキストをダンプする
• 診断コマンドでランナーに過負荷をかける
• 推測に基づいた解決策を実行する（references/を参照）

クイックリファレンス

よくあるエラーパターン

デバッグログ有効化

コマンドリファレンス

ログ分析

# ワークフローログをダウンロード
gh run view <run-id> --log > workflow.log

# ログを分析
node .claude/skills/github-actions-debugging/scripts/analyze-logs.mjs workflow.log

デバッグログ有効化

# リポジトリシークレットを設定
gh secret set ACTIONS_STEP_DEBUG --body "true"
gh secret set ACTIONS_RUNNER_DEBUG --body "true"

# ワークフローを再実行
gh run rerun <run-id>

# クリーンアップ
gh secret remove ACTIONS_STEP_DEBUG
gh secret remove ACTIONS_RUNNER_DEBUG

リソース参照

# デバッグログ詳細
cat .claude/skills/github-actions-debugging/references/debug-logging.md

# 診断コマンド
cat .claude/skills/github-actions-debugging/references/diagnostic-commands.md

# トラブルシューティング
cat .claude/skills/github-actions-debugging/references/troubleshooting-guide.md

検証と記録

スキル構造検証

node .claude/skills/github-actions-debugging/scripts/validate-skill.mjs

使用記録

node .claude/skills/github-actions-debugging/scripts/log_usage.mjs \
  --result success \
  --phase "error-identification" \
  --notes "Permission error resolved"

変更履歴