GitHub AgentOps 実践ガイド

付録C：トラブルシュート（失敗パターンと対処）

仕様不足、差分肥大、テスト失敗、権限不足、Secrets 事故などの失敗パターンと対処を整理します。

仕様不足（Issue が実行仕様になっていない）

症状

  • エージェントの成果がブレる、手戻りが増える
  • レビューで「何が正か」が決まらない

対処（最小）

  • 不足情報を質問として返し、Issue に追記して確定させる
  • 選択肢（案A/案B）と判断材料（メリット/デメリット/リスク）を提示し、決定ログを残す

差分肥大（1PR が大きくてレビューできない）

症状

  • 変更意図が追えない、リスク評価できない

対処（最小）

  • 1PR=1意図で分割（命名/リファクタ/機能変更を混ぜない）
  • 先に安全柵（テスト/静的解析）を置く

テスト失敗/フレーク

症状

  • CI が不安定で、反復が収束しない

対処（最小）

  • 失敗の再現条件（時間、乱数、ネットワーク）を切り分ける
  • 重いテストは nightly 等へ分離し、PR チェックを軽量化する

権限不足（Actions が失敗する/コメントできない）

症状

  • PR コメント投稿が失敗する、リポジトリ書き込みが拒否される

対処（最小）

  • ワークフローの permissions: を確認し、最小権限で不足分だけ付与する
  • フォーク PR は Secrets が渡らない前提で設計し、手動実行/ラベル運用へ寄せる

追加のチェックポイント：

  • Resource not accessible by integration は GITHUB_TOKEN 権限不足の典型（permissions: と既定権限を確認）
  • PR コメント投稿は issues: write が必要になる（PR は issue として扱われる）
  • PR 本文の更新やラベル付与など「書き込み系」は job 単位で権限を付与し、実行条件（イベント/承認）とセットで運用する
permissions:
  contents: read
  issues: write

Secrets 事故（ログ/コメントへの混入）

症状

  • 値の露出、監査上の重大インシデント

対処（最小）

  • 直ちにローテーションし、影響範囲を特定する（値は Issue/PR に貼らない）
  • 再発防止として Rules（forbidden/prompt）と運用手順（レビュー観点）を更新する

ありがちな混入経路：

  • job summary / artifact / キャッシュに .env やログが混ざる
  • 例外スタックトレースやデバッグ出力にトークンが含まれる

対策（最低限）：

  • 生成物の出力前に「機微情報が含まれない」ことを確認する（レビュー観点に含める）
  • 機密が混ざり得るファイルは artifact 対象から除外する（!**/.env 等）

コスト超過（使いすぎ）

症状

  • AI 実行が過剰、Actions が多重起動し、費用/待ち時間が増える

対処（最小）

  • concurrency、paths、手動実行（workflow_dispatch）で対象を絞る
  • 例外対応（緊急時のみ上限緩和）を承認フローとして固定する

concurrency の注意：

  • cancel-in-progress: true により「意図せずキャンセル」されることがある（group 設計を PR 番号などに寄せる）

ドキュメントのリンク切れ/ビルド失敗

症状

  • link-check/ビルドが落ち、公開が止まる

対処（最小）

  • ローカルで品質ゲートを実行し、再現手順を PR に残す
  • 参照先は固定パスを前提にし、移動/改名は移行期間を設ける
Edit this page on GitHub