github-actions-debugging
GitHub Actionsワークフロー実行時のデバッグとトラブルシューティング。Anchors:• Continuous Delivery (Jez Humble) / 適用: パイプライン失敗の診断 / 目的: フィードバックループ短縮• Site Reliability Engineering (Google) / 適用: ログベース障害分析 / 目的: 体系的エラー診断Trigger:Use when debugging failed GitHub Actions workflows, analyzing workflow logs, enabling debug logging, troubleshooting permission/secret/cache/timeout issues, or diagnosing runner environment problems.Keywords: github actions, workflow error, failed job, ACTIONS_STEP_DEBUG, ACTIONS_RUNNER_DEBUG, permission denied, cache miss, timeout, runner diagnostics
When & Why to Use This Skill
This Claude skill provides a systematic framework for debugging and troubleshooting GitHub Actions workflow failures. It streamlines the diagnostic process by analyzing logs, enabling granular debug logging, and inspecting runner environments to significantly reduce the feedback loop in Continuous Delivery pipelines.
Use Cases
- Case 1: Automated log analysis to identify the root cause of pipeline failures and match them against known error patterns like permission issues or timeouts.
- Case 2: Step-by-step guidance for enabling and managing ACTIONS_STEP_DEBUG and ACTIONS_RUNNER_DEBUG to capture detailed diagnostic data without manual configuration overhead.
- Case 3: Troubleshooting complex environment issues such as runner disk space exhaustion, memory limits, or tool version mismatches using specialized diagnostic commands.
- Case 4: Inspecting GitHub Actions context objects (github, env, runner) to resolve issues related to missing secrets, incorrect environment variables, or failed conditional logic.
- Case 5: Implementing a structured debugging workflow that ensures sensitive information is protected while providing actionable reports for rapid incident resolution.
| name | github-actions-debugging |
|---|---|
| description | | |
| • Continuous Delivery (Jez Humble) / 適用 | パイプライン失敗の診断 / 目的: フィードバックループ短縮 |
| • Site Reliability Engineering (Google) / 適用 | ログベース障害分析 / 目的: 体系的エラー診断 |
| Keywords | github actions, workflow error, failed job, ACTIONS_STEP_DEBUG, ACTIONS_RUNNER_DEBUG, permission denied, cache miss, timeout, runner diagnostics |
GitHub Actions Debugging Skill
概要
GitHub Actionsワークフロー実行時のエラー診断、デバッグログ有効化、環境トラブルシューティングを体系的に実施します。
ワークフロー
Phase 1: エラー特定
目的: ワークフローログから失敗の根本原因を特定する
Task: agents/error-identification.md
アクション:
- ワークフローログまたは実行IDを取得
scripts/analyze-logs.mjsでログを分析references/troubleshooting-guide.mdでエラーパターンをマッチング- エラー診断レポートを生成
次のフェーズ: エラーカテゴリに応じて Phase 2, 3, または 4 へ
Phase 2: デバッグログ有効化
目的: 詳細なデバッグログを収集できる状態にする
Task: agents/debug-enablement.md
アクション:
- エラー診断レポートからデバッグレベルを判断
references/debug-logging.mdで設定方法を確認- リポジトリシークレット設定手順を生成
- ワークフロー再実行とクリーンアップ手順を提供
次のフェーズ: 再実行後、Phase 1 に戻る
Phase 3: コンテキスト検査
目的: GitHub Actionsの実行コンテキストから問題を特定する
Task: agents/context-inspection.md
アクション:
- 必要なコンテキストオブジェクト(github、env、runner等)を決定
references/diagnostic-commands.mdでコンテキスト検査コマンドを確認- コンテキストダンプ用のワークフロー修正案を生成
- コンテキスト情報を分析してレポート作成
次のフェーズ: 環境問題が疑われる場合 Phase 4 へ
Phase 4: 環境診断
目的: ランナー環境のリソースとツールを診断する
Task: agents/environment-diagnosis.md
アクション:
- 診断対象(ディスク、メモリ、ツールバージョン等)を決定
references/diagnostic-commands.mdで診断コマンドを確認- 環境診断用ワークフローステップを生成
- 環境情報を分析して解決策を提供
次のフェーズ: 解決策実装後、Phase 1 で検証
Task仕様(ナビゲーション)
各Taskは agents/ ディレクトリに配置されています。実行直前に該当するTaskファイルを読み込んでください。
| Task名 | ファイル | 入力 | 出力 |
|---|---|---|---|
| エラー特定 | agents/error-identification.md |
ログファイルまたは実行ID | エラー診断レポート |
| デバッグログ有効化 | agents/debug-enablement.md |
エラー診断レポート | デバッグ有効化手順書 |
| コンテキスト検査 | agents/context-inspection.md |
エラー診断レポート | コンテキスト分析レポート |
| 環境診断 | agents/environment-diagnosis.md |
エラー/コンテキストレポート | 環境診断レポート |
リソース参照
references/(知識外部化)
| リソース | パス | 内容 |
|---|---|---|
| デバッグログ | references/debug-logging.md | ACTIONS_STEP_DEBUG/RUNNER_DEBUGの詳細 |
| 診断コマンド | references/diagnostic-commands.md | コンテキスト検査・環境診断コマンド |
| トラブルシューティング | references/troubleshooting-guide.md | 一般的なエラーパターンと解決策 |
スクリプト(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/を参照)
クイックリファレンス
よくあるエラーパターン
| エラー | 原因 | 参照先 |
|---|---|---|
| Permission denied | GITHUB_TOKEN 権限不足 | references/troubleshooting-guide.md §1 |
| Cache miss | キャッシュキー不一致 | references/troubleshooting-guide.md §2 |
| Timeout | ジョブ実行時間超過 | references/troubleshooting-guide.md §3 |
| Secret not found | シークレット未設定 | references/troubleshooting-guide.md §4 |
| Runner out of disk | ディスク容量不足 | references/diagnostic-commands.md §3 |
デバッグログ有効化
| 方法 | スコープ | 用途 |
|---|---|---|
| ACTIONS_STEP_DEBUG | リポジトリシークレット | ステップ実行の詳細ログ |
| ACTIONS_RUNNER_DEBUG | リポジトリシークレット | ランナープロセスの診断ログ |
コマンドリファレンス
ログ分析
# ワークフローログをダウンロード
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"
変更履歴
| Version | Date | Changes |
|---|---|---|
| 2.1.0 | 2026-01-02 | references/を整理、Level1-4削除、18-skills.md仕様準拠 |
| 2.0.0 | 2025-12-31 | 18-skills.md spec準拠、agents/追加、Progressive Disclosure適用 |
| 1.0.0 | 2025-12-24 | 初版リリース |