GitHub Actions Error Fixer Skill

GitHub Actions Error Fixer

GitHub Actions の失敗箇所を効率よく発見し、抽出漏れを防ぎながら根本原因を特定して最小限の修正を行う。

入力

次の形式を受け付ける。

$gh-action-error-fixer [--grep-words '<regex>'] [--no-verify] <Action実行URLまたはPR URL>

--no-verify: ローカル検証（ステップ6）をスキップし、CIでの検証に委ねる。修正の正しさをCI上で確認したい場合や、ローカル実行が困難な環境依存テストの場合に指定する。
--grep-words: 失敗ログを抽出する ripgrep の正規表現。省略時は次の既定パターンを使う。
```
 FAILED$|FAILURE:|^FAIL\b|panic:
```
言語固有のキーワードを追加すると精度が上がる。対象リポジトリの主要言語を判定し（workflow YAML の actions/setup-*、ファイル拡張子、ビルドツール等から）、該当する参照ファイルがあれば読み込んで既定パターンに追加する。

| 言語 | 参照ファイル | |------|-------------| | Python | references/python-words.md | | Go | references/go-words.md | | Rust | references/rust-words.md | | JS/TS | references/js-ts-words.md |

ユーザーが --grep-words で明示指定した場合はそちらを優先する。
URL:
- Action job URL: /actions/runs/<run-id>/job/<job-id>
- Action run URL: /actions/runs/<run-id>
- PR URL: /pull/<pr-number>

URL がなく、現在のブランチに紐づく PR から一意に取得できない場合だけユーザーへ確認する。

制約

既存のリポジトリ規約と作業ディレクトリ固有の指示を最初に読む。
gh と rg を使用する。利用できない場合は不足ツールを明示して停止する。
ログ抽出結果だけで原因を確定しない。抽出は調査開始位置の発見に使う。
エラーメッセージ、失敗テスト名、期待値と実値を正確に確認してから修正する。
ユーザーの未コミット変更を保持し、依頼外のリファクタリングやフォールバックを追加しない。
workflow再実行、commit、push、PR更新は、ユーザーが明示的に依頼した場合だけ行う。

ワークフロー

1. 対象を解決する

git status --short --branch で作業状態を確認する。
URL から owner/repo、run ID、job ID、PR番号を取得する。
PR URL の場合は gh pr view の statusCheckRollup から失敗した check と Action URL を特定する。
run URL で job ID がない場合は gh run view <run-id> --repo <owner/repo> --json jobs から失敗した job を特定する。
失敗 job が複数ある場合は、独立して調査する。後続 job の失敗が先行 job の失敗に起因する場合は先行原因を優先する。
matrix strategy の場合は、全環境で共通の失敗か特定環境（OS、言語バージョン等）固有の失敗かを先に切り分ける。共通なら1環境のログで原因を特定し、固有なら環境差異に着目する。
失敗 check が GitHub Actions 以外の場合は、このスキルの対象外であることと取得できた詳細 URL を報告する。

2. ログを三段階で調べる

同じ失敗ログを次の順番で確認する。既定の前後行数は20行とし、情報が切れる場合は50行以上へ広げる。

2-1. キーワード抽出

gh run view <run-id> --repo <owner/repo> --job <job-id> --log-failed \
  | rg -n -C 20 -- '<grep-words>'

失敗テスト名、最初の例外、Caused by、期待値と実値、失敗タスクを探す。結果が多い場合は、判明したテスト名や例外名で再度絞り込む。

2-2. ログ末尾の確認

キーワード抽出の補助として必ず終了部分も確認する。

gh run view <run-id> --repo <owner/repo> --job <job-id> --log-failed | tail -100

終了コード、失敗件数、最終タスク、タイムアウト、OOM、プロセス強制終了を確認する。末尾だけでは、途中に出た最初の失敗を見落とし得るため、単独では原因確定に使わない。

2-3. 完全ログの確認

次の場合はフィルタなしの失敗ログを確認する。

抽出結果と終了理由が一致しない
原因チェーンや失敗前の設定・SQL・HTTP応答が不足している
複数テスト、並列実行、タイムアウト、リソース不足が疑われる
検索語に一致する明確な原因がない

gh run view <run-id> --repo <owner/repo> --job <job-id> --log-failed

完全ログが長い場合はスクラッチパッドディレクトリ（セッション固有の一時ディレクトリ）へ保存し、判明した行番号の前後を sed で段階的に読む。調査後の一時ファイルは削除する。

3. 原因を特定する

PR差分と失敗箇所を対応付ける。
対象コード、テスト、workflow、ビルド設定を読む。
次を区別する。
- PR変更による回帰
- テストの並列干渉またはflaky
- workflow・キャッシュ・依存関係の問題
- 外部サービス・権限・シークレット・runner資源の問題
- PRと無関係な既存障害
ログとコードで説明できる原因仮説を作り、反証となる情報も確認する。
原因を確定できない場合は推測で編集せず、追加調査またはユーザー確認を行う。

4. 修正計画を立てる

実装前に次を簡潔に共有する。

原因と根拠
変更対象と最小修正方針
実行するテスト・Lint
既知のリスクとCIに委ねる検証

複数の修正案で仕様や影響範囲が変わる場合だけ、推奨案を示してユーザーへ確認する。

5. 修正する

編集直前に対象ファイルを読む。
原因へ直接対応する最小差分を実装する。
本番コードを変える場合は、必要な回帰テストも同時に追加する。
自動生成物はリポジトリ所定の生成コマンドで更新し、直接編集しない。
git diff で依頼外の変更が混入していないことを確認する。

6. 検証する

--no-verify 指定時はこのステップ全体をスキップし、「### 7. 報告する」へ進む。検証結果欄には「--no-verify によりスキップ（CIで検証）」と記載する。

変更対象に近い高速なテストを先に実行する。
CIで失敗したテストを可能な範囲で同条件に近づけて実行する。
リポジトリ所定のLint、型チェック、フォーマット、git diff --check を実行する。
DB、コンテナ、外部サービスを使う重いテストは、プロジェクト規約とユーザー指定の環境値（.env.test、docker-compose.test.yml、CI用の環境変数定義、等）を確認してから実行する。
ローカルで再現できない並列条件やrunner固有条件は、未検証として明示する。

7. 報告する

次のテンプレートに沿って結論から報告する。

## 原因
<失敗の根本原因を1-2文で>

## 修正内容
- <変更ファイル>: <変更概要>

## 検証結果
- テスト: <実行結果>
- Lint/型チェック: <実行結果>
- 未検証: <ローカルで再現できなかった条件>

## 次のアクション
- <ユーザーが行う操作（commit/push/workflow再実行など）>

Agent Skills: GitHub Actions Error Fixer

Install this agent skill to your local

Skill Files