Hygiène du cache GitHub
Objectif : répondre d'abord aux questions courantes de lecture GitHub via gitcrawl et le shim gh, puis n'utiliser les appels live à l'API GitHub que lorsque la fraîcheur ou les écritures sont nécessaires.
Chemin par défaut
Utilisez gh normalement. Sur les machines de Peter, il est attendu que ce soit le shim gitcrawl, donc les lectures supportées peuvent être répondues localement ou mises en cache sans changer les commandes.
Privilégiez ces lectures locales/mises en cache :
gitcrawl sync owner/repo --numbers 123 --with pr-details
gh search issues "<termes>" -R owner/repo --state open --json number,title,state,url,updatedAt,labels,author
gh search prs "<termes>" -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,comments,labels,url
gh pr view 123 -R owner/repo --json number,title,state,body,comments,labels,files,commits,statusCheckRollup,url
gh pr checks 123 -R owner/repo --json name,state,detailsUrl,workflow
gh run list -R owner/repo --branch nom-de-branche --json databaseId,workflowName,status,conclusion,url
gh pr diff 123 -R owner/repo --patch
Utilisez des références exactes et des champs réduits. Évitez les boucles larges comme un gh issue view par résultat alors qu'un seul gh search ou gh issue list --json ... peut répondre à la première question.
Pour CI, évitez les boucles de polling serrées gh run list / gh run view. Après un push ou un déclenchement de workflow, identifiez un run exact, puis interrogez-le avec backoff. Ne récupérez les logs complets que pour les jobs en échec ou lorsque l'utilisateur demande explicitement des logs. Les endpoints de logs REST Actions de type gh run view --log, --log-failed et les endpoints courants sont mis en cache plus longtemps par gitcrawl, tandis que le statut du run reste à courte durée de vie.
Fraîcheur
Les réponses locales sont bonnes pour la découverte, la recherche de doublons, la revue de vieux fils, le tri par auteur/étiquette, et les vérifications du type « existe-t-il déjà une issue/PR ? ».
Utilisez un appel live quand :
- écrire, commenter, fermer, fusionner, relancer ou éditer
- vérifier l'état final actuel avant une action de mainteneur
- vérifier le statut CI après un push
- le résultat local est manquant ou visiblement obsolète
- l'utilisateur demande l'état le plus récent/actuel
Pour la revue de PR, préférez hydrater les détails exacts de la PR une fois avec gitcrawl sync owner/repo --numbers <n> --with pr-details lorsque vous savez que vous inspecterez fichiers, commits, vérifications ou résumés de run plusieurs fois. Le shim gh peut auto-hydrater une PR exacte en cas d'absence, en utilisant GITHUB_TOKEN ou gh auth token ; l'hydratation explicite rend l'intention et le coût plus clairs.
Après une écriture, faites une relecture ciblée, pas une renumérisation large.
XCache
Inspectez le comportement du cache lorsque des limites de débit sont suspectées :
gh xcache stats
gh xcache keys
gh xcache gc
Lisez backend_misses_by_command et backend_misses_by_route dans gh xcache stats --json avant d'ajouter de nouvelles boucles live GitHub. Ces cartes montrent quelles formes de commandes échappent encore au cache.
Utilisez gh xcache flush uniquement lorsqu'une réponse de fallback mise en cache obsolète induit en erreur une décision.
Pour une preuve uniquement locale, rendez temporairement le backend indisponible pour une seule commande :
GITCRAWL_GH_PATH=/tmp/no-real-gh gh search issues "<termes>" -R owner/repo --json number,title,url
Étiquette d'agent
Regroupez les questions par dépôt et par état. Réutilisez les données déjà affichées dans la session. Limitez le polling CI ; inspectez les logs uniquement pour les runs en échec ou le run exact examiné. Ne contournez pas le shim avec /opt/homebrew/opt/gh/bin/gh sauf pour diagnostiquer le shim lui-même.