github-cache-hygiene

GitHub キャッシュの衛生管理

目標：まずローカルの Gitcrawl アーカイブを検索し、その後、既存の Octopool 対応 gh シムを使用して、最新の GitHub メタデータを取得し、許可された書き込みを行います。

デフォルトの手順

まずローカルアーカイブを読み取ります。

gitcrawl search prs "<terms>" -R owner/repo --state open --json number,title,url

gitcrawl threads owner/repo --numbers 123 --include-closed --json

--include-closed を指定すると、クローズ済みまたはマージ済みの候補も対象になります。アーカイブの状態は GitHub の状態より遅れている場合があり、現在の状態を証明するものではありません。

最新のメタデータが必要な場合は、次に PATH 上の通常の gh を使用します。Peter のマシンでは Octopool 対応シムが使われている想定なので、サポート対象の JSON 読み取りでは、認証やコマンドのルーティングを変更せずに、フリートのキャッシュを共有します。

gh search issues "<terms>" -R owner/repo --state open --json number,title,state,url,updatedAt,labels,author
gh search prs "<terms>" -R owner/repo --state open --json number,title,state,url,updatedAt,isDraft,author
gh issue list -R owner/repo --state open --author user --assignee user --label bug --json number,title,url
gh pr list -R owner/repo --state open --author user --label dependencies --json number,title,url
gh issue view 123 -R owner/repo --json number,title,state,body,labels,url
gh pr view 123 -R owner/repo --json number,title,state,url,headRefName,headRefOid
gh pr checks 123 -R owner/repo --json name,state,bucket,link
gh run list -R owner/repo --branch branch-name --json databaseId,workflowName,status,conclusion,url
gh pr diff 123 -R owner/repo --patch

正確な参照先と必要最小限のフィールドを指定します。--json は出力を選択するものであり、読み取り元の識別には使われません。 Octopool 0.7.1 では、PR の mergeStateStatus と issue の comments を指定すると、フィールドの組み合わせ全体でネイティブの gh が選択されます。PR のコメント、レビュー、コミットのエクスポートも、引き続きネイティブで処理されます。必要な場合はこれらのフィールドを指定しますが、それらを使用しない説明用の読み取りでは省略します。キャッシュの再利用率を上げるためだけにマージやレビューのゲートを削除したり、一貫性の要件を維持せずに、1つの判断を別々のタイミングで行う読み取りに分割したりしないでください。

サポート対象の人間向け出力や、認識対象のランディング用 GraphQL プロジェクションも中継できます。サポート対象の gh api --paginate／--slurp および --hostname github.com による読み取りも、Octopool を迂回する必要はありません。インストール済みバージョンの CLI の仕様と、実際に観測されたルーティングを使用してください。gh の絶対パスだけでは、それがネイティブのバイナリであるとは判断できません。

単一の gh search または gh issue list --json ... で最初の調査に答えられる場合は、検索結果ごとに gh issue view を実行するような広範なループを避けてください。

CI では、短い間隔で gh run list／gh run view を繰り返しポーリングしないでください。プッシュまたはワークフローのディスパッチ後、正確な実行を1つ特定し、その実行を対象とするウォッチャーを使うか、30秒、60秒、120秒の間隔でその実行をポーリングしてください。 想定される head SHA と実行回数を確認してください。最新の上流データを取得した直後でも、広範な一覧やフィルター付きの一覧には遅延が生じることがあります。最新行は、CI の最終的な証拠にはなりません。失敗後、または明示的に要求された場合に限り、ログを1回取得してください。完了済みの実行は再読み込みせず、以前の出力を再利用してください。

最新性

ローカルの結果は、調査、重複検索、古いスレッドの確認、作成者やラベルのトリアージ、「既に issue／PR がある可能性が高いか」の確認に適しています。

次の場合はライブ呼び出しを使用してください。

• 書き込み、コメント、クローズ、マージ、再実行、編集を行うとき
• メンテナーの操作の前に、現在の最終状態を確認するとき
• プッシュ後に CI の状態を検証するとき
• ローカルの結果がない、または明らかに古いとき
• ユーザーが最新またはライブの状態を求めているとき

繰り返し確認する際に、ローカルアーカイブでファイル、コミット、チェック、または実行の概要が必要な場合に限り、正確な PR 詳細を最新化してください。

gitcrawl sync owner/repo --numbers 123 --with pr-details

この更新では GitHub API 呼び出しを消費し、Gitcrawl のアーカイブを更新しますが、Octopool の別個の gh キャッシュは更新しません。通常の gh による読み取りでは、Gitcrawl のアーカイブは自動的に最新化されません。

gitcrawl gh は廃止されており、移行に関するメッセージを表示して 2 で終了します。該当する手順は、アーカイブの読み取りに続いて通常の gh を使う形に置き換えてください。このメッセージは認証エラーではありません。廃止されたコマンドを修復するために、octopool login を実行したり、トークン、認証、PATH、設定を変更したり、既存のシムを迂回したりしないでください。

書き込み後は、広範な再スキャンをせず、対象を絞った最新の読み戻しを1回行ってください。 中継読み取りでは、OCTOPOOL_FRESH=1 または明示的な Cache-Control: max-age=0 を使用してください。 state、headRefOid、statusCheckRollup など、サポート対象の PR 判断用フィールドは自動的に再検証されます。title などの説明用フィールドでは、キャッシュが再利用されることがあります。

gh api --include はネイティブの gh と呼び出し元の認証情報を使用します。これは識別情報やクォータ、場合によっては可視性も変えるため、最新性を切り替える機能でも、古い一覧を確実に回避する方法でもありません。呼び出し元が所有する権限とマージの判断は、必須の識別情報経路を維持してください。中継による最新の MISS が古い一覧と同時に発生しても、それだけでキャッシュの再利用期限切れを証明するわけではありません。また、再検証後に HIT が発生しても、上流へのリクエストがゼロだったことを証明するわけではありません。

Octopool

レート制限が疑われる場合は、キャッシュの動作を確認してください。

octopool whoami
octopool health
octopool stats --since 1h
octopool stats --since 24h --json

キャッシュされた対象レスポンス数を、対象リクエスト数で割った値を優先して確認してください。UTC の時間枠、分子、分母、キャッシュミス、キャッシュを経由しなかったリクエスト、リクエストの集約数を保持してください。変化の原因を特定する前に、ルートとクライアントの構成、明示的な鮮度設定、レイテンシを比較してください。これらはレスポンス再利用の指標であり、GitHub のクォータ削減量ではありません。プールの合計値はすべての呼び出し元を対象とする一方、クライアントの表は認証済みの呼び出し元を対象とします。ネイティブ GraphQL と直接クライアントはリレーの指標に含まれません。サンプルの対象期間内に見つからないことは、インストールが壊れている証拠ではありません。

実際の実行コンテキストを確認してください。ホスト側の shim が動作していても、コンテナでは別のネイティブ読み取り専用ラッパーが使われていることがあります。そのラッパーの許可リストと認証情報の境界を維持してください。キャッシュの対象範囲を広げるために、ホストの変更用認証情報をマウントしてはいけません。

OCTOPOOL_NO_FALLBACK=1 は、対象範囲を限定した、サポートが確認済みのリレー読み取りに限って使用してください。これはリレーからネイティブへの引き継ぎをブロックしますが、意図的にサポート対象外としているコマンドは、引き続き直接委譲される場合があります。そのため、成功しただけではリレーが常に使われている証明にはなりません。サポートが確認済みのコマンドと、観測されたルート／キャッシュの証拠を組み合わせてください。別のネイティブラッパーは、この変数をまったく無視する場合があります。グローバルには設定しないでください。変更操作とサポート対象外の読み取りには、引き続き実際の gh が必要です。

リレーのみであることを確認するには：

OCTOPOOL_NO_FALLBACK=1 gh api repos/owner/repo --jq .full_name

エージェントのエチケット

質問はリポジトリと状態ごとにまとめてください。セッション中にすでに表示されたデータを再利用してください。CI のポーリングは間隔を空け、失敗した実行のログ確認は一度だけにしてください。通常の読み取りと許可された書き込みには、PATH 上の gh をそのまま使用し、実際の CLI へのフォールバックは Octopool に任せてください。廃止された Gitcrawl のレシピを置き換えるために、shim を回避して実際の gh の絶対パスやバイナリーの上書きを使わないでください。