babysit

PR を見守る

まずマージ可能か確認してから、gh のウォッチャーを 1 つ実行し、そのプロセスが終了するまで待ちます。成功とは、現在の PR の head に対して意図したチェックが完了し、失敗や未実行のチェックがすべて把握されている状態を意味します。見守りは、マージ、ゲートの回避、レビューコメントの投稿を許可するものではありません。

待つ前に競合を確認する

PR 番号とリポジトリを常に明示して使用します。

gh pr view <n> -R <owner/repo> --json state,url,headRefOid,baseRefName,baseRefOid,mergeable,mergeStateStatus,isDraft,reviewDecision

head SHA、ベースブランチ、ベース SHA を記録します。PR がクローズまたはマージされた場合は、監視を停止します。ウォッチャーを開始する前に、mergeable を確認します。

• CONFLICTING：監視のみの依頼であれば、競合を報告します。修正が許可されている場合は、この PR の現在のベースに対して resolve-pr-conflicts を使用し、プッシュ後にこの確認を繰り返します。
• UNKNOWN：GitHub はマージ可能かどうかを確定していません。少し待ってから再確認し、それでも不明な場合は、取得した head と base をローカルで調査するか、未解決の状態を報告します。競合がないと決めつけたり、無期限に繰り返したりしないでください。
• MERGEABLE：続行します。他のマージゲートによって PR がブロックされる場合もあります。mergeStateStatus: BLOCKED だけでは、テキスト上の競合があるとは判断できません。

マージ競合がある間、GitHub は pull_request でトリガーされるワークフローを実行しません。先に競合を解決することで、開始できないチェックを待たずに済みます。GitHub のワークフローのトラブルシューティングを参照してください。

gh にチェックを監視させる

gh pr checks <n> -R <owner/repo> --watch --interval 10

PR チェックコマンドはデフォルトで 10 秒ごとに更新し、報告されたチェックが完了するまで待機します。失敗時にすぐ修正へ移りたい場合は、--fail-fast を使用します。タスクが必須チェックだけを対象とする場合に限り、--required を追加します。これを指定すると、レビュー bot の任意チェックが除外される場合があります。

コマンドは長時間実行プロセスとして 1 回だけ実行します。実行ツールの完了通知を利用するか、同じセッションで十分な時間を設定して待機します。新たに gh pr checks を呼び出してモデル主導のスリープと交互に実行したり、ツールが制御を返すたびにウォッチャーを再起動したり、変化のない更新を逐一伝えたりしないでください。

これは CLI が管理するポーリングであり、サーバーイベントの購読ではありません。実装は、チェックが保留中の間は更新を続け、残りがなくなると終了します。後から作成されたチェックや、将来のレビューコメントを購読し続けることはありません。

最終出力と終了ステータスを確認します。チェックが失敗すると、ゼロ以外の値が返されます。通常の watch 以外の出力では、保留中のチェックがあると終了コード 8 が返されます。認証、API、チェック不足に関するエラーも診断が必要です。構造化された詳細が役立つ場合は、別途スナップショットを取得します。

gh pr checks <n> -R <owner/repo> --json name,bucket,state,workflow,link

--json と --watch を組み合わせないでください。JSON はスナップショットであり、正常にエクスポートできてもチェックに合格したことの証明にはなりません。bucket の値を確認してください。キャンセルまたはスキップされたチェックは、意図したテストが実行された証拠にはなりません。

完了しないチェックへの対処

チェックが報告されていない場合、ウォッチャーは作成を待たずにエラーで終了します。想定されるチェックが見つからない場合や、保留中のチェックが通常の実行時間を超えて進展しない場合は、ワークフローと実行の詳細を確認してください。状況に応じて、競合、トリガー／パスフィルター、スキップ注釈、ワークフローの承認、利用できないランナーを再度確認してください。実行できないワークフローに対して、ウォッチャーを繰り返し再起動しないでください。ブロッカーが解消されたら再開し、それ以外の場合はブロッカーを報告してください。

既知の GitHub Actions の実行には、専用の ID を指定してください。

gh run watch <run-id> -R <owner/repo> --exit-status --compact --interval 10
gh run view <run-id> -R <owner/repo> --log-failed

実行ウォッチャーが対象にするのは 1 回の Actions 実行であり、すべての PR チェックではありません。--exit-status を指定すると、実行が失敗した場合にゼロ以外の値が返されます。細粒度 PAT 認証には対応していません。必要に応じて失敗ログを確認してください。許可されたタスクの範囲内で修正してプッシュし、競合チェックからやり直してください。診断せずに失敗を繰り返し再実行しないでください。

チェックを公開するレビューサービスは、gh pr checks で監視できます。コメントやレビューのみを投稿するサービスは、これらのウォッチャーの対象外です。利用できる場合は、そのサービスの完了確認手段を使用してください。そうでない場合は、CI が成功したことをレビュー完了と見なさず、その制限を報告してください。

結果を確認する

ウォッチャーの終了後に、PR の状態、ヘッド SHA、ベースブランチと SHA、およびマージ可能性を読み直してください。チェックの最終スナップショットを取得し、想定されるチェックが表示されたことを確認してください。ヘッドが変更されていた場合は、新しいヘッドについて事前確認とチェックの監視を繰り返してください。ベースのみが変更された場合は、マージ可能性とリポジトリの最新性要件を再評価してください。その変更だけを理由に、完了済みのチェックを再実行しないでください。ウォッチャーが終了しただけでは、マージ可能であることやレビューの承認が証明されたことにはなりません。

PR、確認済みのヘッド SHA、チェック結果、レビューまたはワークフローのブロッカーを報告してください。ユーザーのタスクで承認されている場合にのみ、マージに進んでください。