prcheckloop

PRCheckloop

GitHub PR のチェックをすべてグリーンにするか、具体的なブロッカーを明示して終了します。

スコープ

• GitHub PR のみが対象です。リポジトリが GitLab の場合は停止し、check-pr を使用してください。
• 古いコミットではなく、最新の PR head SHA に対するチェックに焦点を当てます。
• レビューコメントや PR テンプレートの整理ではなく、CI／ステータスチェックに焦点を当てます。
• ユーザーがレビューコメントの整理も希望している場合は、これと check-pr を組み合わせてください。

入力

• PR 番号（任意）：指定されていない場合は、現在のブランチの PR を検出します。
• 最大反復回数：デフォルトは 5 です。

ワークフロー

1. PR を特定する

PR 番号が指定されていない場合は、現在のブランチから検出します。

gh pr view --json number,headRefName,headRefOid,url,isDraft

必要に応じて、変更を加える前に PR ブランチへ切り替えます。

次の場合は早期に停止します。

• gh が認証されていない
• ブランチに対応する PR がない
• リポジトリが GitHub 上でホストされていない

2. 最新の head SHA を追跡する

常に現在の PR head SHA を対象に作業します。

PR_JSON=$(gh pr view "$PR_NUMBER" --json number,headRefName,headRefOid,url)
HEAD_SHA=$(echo "$PR_JSON" | jq -r .headRefOid)
PR_URL=$(echo "$PR_JSON" | jq -r .url)

古い SHA の失敗チェックは無視します。プッシュするたびに HEAD_SHA を更新し、検査ループを最初からやり直します。

3. 対象 SHA のチェックを一覧にする

GitHub のチェック実行と従来のコミットステータスコンテキストの両方を取得します。

gh api "repos/{owner}/{repo}/commits/$HEAD_SHA/check-runs?per_page=100"
gh api "repos/{owner}/{repo}/commits/$HEAD_SHA/status"

PR の状態を簡潔に確認するには、次の GraphQL ペイロードが便利です。

gh api graphql -f query='
query($owner:String!, $repo:String!, $pr:Int!) {
  repository(owner:$owner, name:$repo) {
    pullRequest(number:$pr) {
      headRefOid
      url
      statusCheckRollup {
        contexts(first:100) {
          nodes {
            __typename
            ... on CheckRun { name status conclusion detailsUrl workflowName }
            ... on StatusContext { context state targetUrl description }
          }
        }
      }
    }
  }
}' -F owner=OWNER -F repo=REPO -F pr="$PR_NUMBER"

4. チェックが実際に実行されるまで待つ

新しいプッシュの後、チェックが表示されるまで少し時間がかかることがあります。次のいずれかに該当するまで、15～30 秒ごとにポーリングします。

• チェックが表示され、すべての項目が終了状態になっている
• チェックが表示され、少なくとも 1 つ失敗している
• 通常 2 分ほど待ってもチェックが表示されない

次の状態は成功として扱います。

• チェック実行：SUCCESS、NEUTRAL、SKIPPED
• ステータスコンテキスト：SUCCESS

次の状態は保留中として扱います。

• チェック実行：QUEUED、PENDING、WAITING、REQUESTED、IN_PROGRESS
• ステータスコンテキスト：PENDING

次の状態は失敗として扱います。

• チェック実行：FAILURE、TIMED_OUT、CANCELLED、ACTION_REQUIRED、STARTUP_FAILURE、STALE
• ステータスコンテキスト：FAILURE、ERROR

最新の SHA に対するチェックが表示されない場合は、.github/workflows/、ワークフローのパスフィルター、ブランチ保護の要件を調べます。リポジトリ側で原因を特定または修正できないチェックについては、エスカレーションします。

5. 失敗したチェックを調査する

GitHub Actions の失敗については、現在の SHA に対する実行と失敗ログを調べます。

gh run list --commit "$HEAD_SHA" --json databaseId,workflowName,status,conclusion,url,headSha
gh run view <RUN_ID> --json databaseId,name,workflowName,status,conclusion,jobs,url,headSha
gh run view <RUN_ID> --log-failed

失敗したチェックごとに、次のように分類します。

失敗の種類	対応
コード／テストのリグレッション	ローカルで再現し、修正して検証します
リント／型／ビルドの不一致	ワークフロー内の該当するローカルコマンドを実行し、修正します
フレークまたは一時的なインフラストラクチャの問題	フレークである根拠があれば、一度再実行します
外部サービス／ステータスアプリの失敗	詳細 URL と担当者の推定を添えてエスカレーションします
シークレット／権限／ブランチ保護の不足	直ちにエスカレーションします

コード変更を伴わずに失敗したジョブを再実行するのは一度だけにしてください。再実行を繰り返してはいけません。

6. 対処可能な失敗を修正する

チェックアウト済みのコードで対処可能な失敗の場合：

1. ワークフローまたは失敗したコマンドを読み、実際の判定条件を特定します。
2. 妥当な範囲でローカル再現します。
3. 正しく動作する最小限の修正を行います。
4. まず対象を絞った検証を実行し、必要に応じてその後に広範な検証を行います。
5. 内容に即したコミットを作成します。
6. PR を再確認する前にプッシュします。

ローカルで修正しただけで終了してはいけません。新しい head SHA に対するリモート PR のチェックがグリーンになったときにのみ、ループは完了します。

7. プッシュして繰り返す

修正するたびに、次を実行します。

git push
sleep 5

次に PR のメタデータを更新して新しい HEAD_SHA を取得し、ステップ 3 からやり直します。

次のいずれかに該当する場合にのみ、ループを終了します。

• 最新の head SHA に対するすべてのチェックがグリーンになった
• 妥当な修正を試みた後もブロッカーが残っている
• 最大反復回数に達した

8. ブロッカーを正確にエスカレーションする

PR のチェックをすべてグリーンにできない場合は、次を報告してください。

• PR の URL
• 最新の head SHA
• 失敗または未実行のチェックの正確な名前
• 詳細を確認できる URL
• すでに試したこと
• ブロックされている理由
• 誰がブロッカーを解除すべきか
• 次に実行する具体的なアクション

ブロッカーの例：

• 外部ステータスアプリの障害
• GitHub シークレットまたは権限の不足
• ブランチ保護設定における必須チェック名の不一致
• 1 回再実行しても続く不安定なテスト
• 手元にない認証情報またはインフラストラクチャへのアクセスが必要な失敗

出力

スキルの完了時に、次を報告してください。

• PR の URL とブランチ
• 最終的な head SHA
• グリーン／保留中／失敗のチェック概要
• 実施した修正と検証内容
• 変更をプッシュしたかどうか
• すべてのチェックがグリーンでない場合は、ブロッカーの概要

メモ

• このスキルは check-pr より意図的に範囲を絞っており、PR チェックの修復ループです。
• このスキルは greploop を補完します。Greptile のチェックが完璧でも、CI がレッドのままの場合があります。