gh-action-run-validator Skill

gh-action-run-validator

GitHub Actionsのworkflow実行ログを取得・分析し、workflow定義との整合性検証、エラー原因分析、改善提案を行います。

注意: このSkillを使用する際のユーザーとのやり取りはすべて日本語で行います。

Degrees of Freedom

引数の解析: Low freedom — 以下の「引数の解析」セクションのパターンに厳密に従う。パターンに合致しない場合は必ずユーザーに確認する
ログ分析の深さ: Medium freedom — 失敗したstepは詳細に分析し、成功したstepは概要のみ。ただしユーザーが特定stepの詳細を求めた場合は掘り下げる
改善提案: High freedom — 検出した問題の性質に応じて、具体的な修正コード・設定変更・ベストプラクティスを自由に提案してよい

引数の解析

$ARGUMENTS を以下のパターンでパースする:

| パターン | 例 | 解釈 | |---------|-----|------| | https://github.com/{owner}/{repo}/actions/runs/{run_id} | https://github.com/myorg/myrepo/actions/runs/12345 | URL形式 | | {owner/repo} {run_id} | myorg/myrepo 12345 | リポジトリ+RUN ID | | 引数なし | （空） | ユーザーにURL or owner/repo + run_idを確認 |

URL解析ルール: URLからは owner/repo と run_id を抽出する。URLにクエリパラメータやフラグメントが付いていても正しく抽出すること。

前提条件

gh CLI がインストール済みで認証済みであること
対象リポジトリへの読み取り権限があること

実行フロー

Phase 1: データ収集

以下の情報を gh CLI で取得する。可能な限り並列で実行すること。

1-1. Run概要の取得

gh run view {run_id} --repo {owner/repo}

取得する情報:

workflow名、ブランチ、トリガーイベント、実行ステータス
各jobの名前・ステータス・所要時間

1-2. 各Jobのログ取得

gh run view {run_id} --repo {owner/repo} --log

失敗したjobがある場合は --log-failed も活用してエラー箇所を効率的に特定する:

gh run view {run_id} --repo {owner/repo} --log-failed

ログが大量の場合は全量を読み込まず、失敗stepのログを優先的に分析すること。

1-3. Workflow定義ファイルの取得

Runの概要から workflow ファイル名を特定し、リポジトリからYAMLを取得する:

gh api repos/{owner}/{repo}/actions/runs/{run_id} --jq '.path'

取得したパスを使ってファイル内容を取得:

gh api repos/{owner}/{repo}/contents/{workflow_path} --jq '.content' | base64 -d

--jq '.head_branch' でブランチを確認し、必要に応じて ?ref={branch} パラメータを付与する。

Phase 2: 整合性チェック

Workflow YAML定義と実際の実行結果を照合し、以下を確認する:

Job実行順序の検証
- needs で定義された依存関係通りにjobが実行されたか
- 条件付きjob（if 条件）が意図通りにスキップ/実行されたか
Step実行の検証
- 各stepが定義通りの順序で実行されたか
- if 条件付きstepが期待通りに動作したか
- continue-on-error: true のstepが失敗しても後続が実行されているか
環境・変数の検証
- env や secrets の参照エラーがないか（ログ中の "undefined" や空文字の警告を検出）
- matrix strategyが期待通りに展開されているか
Artifact/Cache検証
- upload/download artifactが正常に動作しているか
- cacheのhit/miss状況

Phase 3: エラー原因分析

失敗したstepがある場合、以下の観点で根本原因を特定する:

エラーメッセージの分類
- コマンド実行エラー（exit code != 0）
- 依存関係エラー（パッケージのインストール失敗等）
- テスト失敗（テストフレームワークの出力をパース）
- タイムアウト
- 権限・認証エラー
- リソース制限（ディスク、メモリ等）
エラーの連鎖分析
- 最初に失敗したstep/jobを特定（根本原因と二次的失敗を区別）
- needs 依存による連鎖的なjob失敗を追跡
一時的な問題 vs 永続的な問題の判別
- ネットワークエラー、レート制限などの一時的問題か
- コードや設定の問題で再実行しても解消しない永続的問題か

Phase 4: レポート出力

以下の構造で検証レポートを出力する:

## 検証レポート: {workflow名}

### 実行概要
- **リポジトリ**: {owner/repo}
- **Run ID**: {run_id}
- **ブランチ**: {branch}
- **トリガー**: {event}
- **ステータス**: {status}
- **所要時間**: {duration}

### 実行結果サマリ

| Job | ステータス | 所要時間 | 備考 |
|-----|-----------|---------|------|
| ... | ...       | ...     | ...  |

### 整合性チェック結果
（workflow YAML定義と実行結果の照合結果。問題がなければ「問題なし」と明記）

### エラー分析（失敗時のみ）
#### 根本原因
（最初に失敗したstepとその原因）

#### エラー詳細
（関連するログ抜粋とその解釈）

#### 連鎖的影響
（根本原因から派生した二次的な失敗がある場合）

### 改善提案
（問題の修正方法、workflow最適化の提案。具体的なYAMLコード例を含める）

注意事項

ログにsecretやトークンの値が含まれる場合があるため、レポートにそのまま引用しないこと。*** でマスクされた値はそのまま表示して問題ない
大規模なログ（数万行）の場合は、失敗箇所周辺に絞って分析すること。全量読み込みはコンテキストを圧迫する
gh コマンドが認証エラーを返した場合は、ユーザーに gh auth login の実行を案内する

Agent Skills: gh-action-run-validator

Install this agent skill to your local

Skill Files