| name | ci-fix |
| description | GitHub Actions や CI の失敗を調査し、原因を切り分けて修正するときに使う。ユーザーが「CI 落ちてる」「GitHub Actions 直して」「workflow が失敗」「checks が red」「test failure を直して」「lint/build が CI でだけ落ちる」などを依頼した場合は必ず使う。gh CLI、workflow ログ、ローカル再現、最小修正、再検証、PR 反映までを安全な順序で進める。 |
CI Fix
目的
GitHub Actions / CI の失敗を、ログの症状だけで場当たり的に直さず、失敗箇所、再現条件、原因、修正、再検証を根拠付きでつなげる。
CI は複数の job、matrix、環境差、キャッシュ、依存サービス、権限、secret、外部 API にまたがるため、最初に観測範囲を狭める。修正は可能な限りローカルで再現できる形に落とし込み、CI 専用の一時しのぎを避ける。
基本方針
- まず失敗した check、workflow、job、step、ログの該当箇所を特定する。
- ログ全体を貼り付けず、エラー、直前の実行コマンド、環境差が分かる範囲を読む。
- 同じエラーが複数 job に出ている場合は、最初の根本原因を優先する。
- ローカル再現できる失敗は、CI を再実行する前にローカルで直す。
- CI でだけ失敗する場合は、OS、shell、working directory、env、permissions、cache、services、secrets、toolchain version を疑う。
- 実装修正が必要な場合は
$code-general を併用する。
- テストや検証コマンドの追加、flake 対策、回帰テストが必要な場合は
$code-test を併用する。
- PR 作成や更新まで進める場合は
$cmd-create-pr に引き継ぐ。
事前確認
最初に現在位置と PR / check の状況を確認する。
git status --short --branch
git branch --show-current
gh pr status
PR 番号が分かる場合は、check 一覧を確認する。
gh pr checks <pr-number>
PR 番号が不明な場合は、現在ブランチの PR を確認する。
gh pr view --json number,title,url,headRefName,baseRefName,statusCheckRollup
調査手順
- 失敗している workflow / job / step を特定する。
- 失敗ログから、実行コマンド、エラーメッセージ、直前の setup step、matrix 条件を抜き出す。
- 失敗が次のどれに近いか分類する。
- Code failure: テスト、lint、typecheck、build、format が実装差分で壊れている。
- CI definition failure: workflow YAML、working directory、permissions、path filter、artifact、cache key、service container が壊れている。
- Environment drift: Node / Go / Ruby / Python / OS / shell / dependency version の差で壊れている。
- Secret or permission failure: token、secret、OIDC、GitHub permissions、fork PR 制約で壊れている。
- Flake or external dependency: timing、並列実行、ネットワーク、外部 API、rate limit、順序依存で壊れている。
- 関連する workflow ファイル、実行コマンド、直近差分を読む。
- ローカル再現コマンドを決める。CI の step と同じ working directory、env、toolchain をできるだけ揃える。
- 最小修正を実装する。
- ローカル検証を実行する。
- 必要に応じて CI を再実行し、同じ失敗が解消したことを確認する。
- 修正内容、根本原因、検証結果、残るリスクを報告する。
GitHub Actions ログ確認
gh pr checks で失敗 check の名前を確認する。
gh pr checks <pr-number>
詳細が必要な場合は run を特定する。
gh run list --branch <branch-name> --limit 10
gh run view <run-id> --json name,status,conclusion,event,headBranch,headSha,jobs
ログを読む場合は、失敗 job に絞る。大量ログを読む前に job 名と step 名を特定する。
gh run view <run-id> --job <job-id> --log
ログから見るポイント:
Run ... の実行コマンドworking-directoryenv- toolchain setup の version
- 最初に失敗した assertion、compile error、lint error、permission error
- 後続の cascade failure ではなく root failure
修正の判断基準
Code failure
- CI step と同じコマンドをローカルで実行する。
- テスト失敗は、失敗したテスト名、入力、期待値、実際値を確認する。
- lint / typecheck は、指摘の意味を理解してから修正する。
- 実装を変える場合は
$code-general を使い、既存仕様と公開契約を壊さない。
- バグ修正なら、再発しやすい領域に回帰テストを追加するか検討する。
CI definition failure
- workflow YAML の構文、indent、job dependency、permissions、shell、working directory を確認する。
- path filter や matrix 条件が意図した job を動かしているか確認する。
- cache は高速化のための補助として扱い、cache hit 前提でしか通らない構成にしない。
- artifact や generated file は、作成 step と参照 step の job 境界を確認する。
Environment drift
- CI とローカルの toolchain version を比較する。
- version を pin するか、既存の
.tool-versions、go.mod、packageManager、lockfile、Dockerfile に合わせる。
- 依存更新で直す場合は、lockfile 変更の影響を確認する。
- CI だけの workaround ではなく、プロジェクトの標準環境を明確にする。
Secret or permission failure
- secret 値そのものを表示しない。
- secret が必要な workflow か、fork PR で secret が渡らないケースか確認する。
permissions が不足している場合は、必要最小限の権限だけ追加する。- token や secret の新規発行、設定変更が必要な場合は、ユーザーに判断を戻す。
Flake or external dependency
- 失敗が再実行で消えるかだけで終わらせず、flake の原因を探す。
- sleep、時刻、乱数、並列実行、共有リソース、外部 API、rate limit を確認する。
- テスト側で同期、固定 seed、依存の分離、タイムアウトの明確化を検討する。
- 再実行が妥当な場合も、flake の観測結果を報告に残す。
CI 再実行
CI 再実行は、ログ確認とローカル修正後に行う。
gh run rerun <run-id> --failed
再実行する前に確認すること:
- 未コミット変更が CI に反映されない状態ではないか。
- push が必要な場合、直接
git push せず、リポジトリの安全手順に従っているか。
- 外部サービスや課金リソースを消費する workflow ではないか。
完了条件
- 失敗した workflow / job / step と root cause を説明できる。
- 修正差分が root cause に対応している。
- 関連するローカル検証が通っている。
- CI の再実行または代替根拠で、同じ失敗が解消したことを確認している。
- CI でだけ確認できる項目が未確認の場合は、その理由と次の確認手順を残している。
報告形式
最終報告は次を簡潔に含める。
CI 修正結果:
- 失敗箇所: <workflow / job / step>
- 原因: <root cause>
- 修正: <変更内容>
- 検証: <ローカル検証と CI 再実行結果>
- 残るリスク: <flake、外部依存、未確認事項があれば>
PR に反映する場合は、commit、push、PR description 更新を $cmd-create-pr の手順へつなげる。
