CommunityRédaction et éditiongithub.com

GitHub CLI (gh)

Interagissez avec GitHub depuis la ligne de commande de manière efficace et économe en jetons pour des workflows agentiques fiables.

Qu'est-ce que GitHub CLI (gh) ?

Cette compétence permet à un agent IA d'interagir avec GitHub via l'outil en ligne de commande `gh`, couvrant les dépôts, les versions, les issues, les pull requests, les discussions, la recherche, la revue de code et GitHub Actions. Elle est conçue pour être économe en jetons, privilégiant les formats texte par défaut et des stratégies comme le clonage temporaire pour l'exploration de code inconnu. Testée avec `gh` 2.95.0, elle fournit des directives précises pour l'agent : utiliser `gh repo read-file` pour les fichiers connus, cloner pour la recherche multi-fichiers, et toujours confirmer les opérations d'écriture. La compétence détaille les commandes pour les issues, les PRs, les releases, les discussions, la recherche (y compris le code et les commits), avec des flags communs et des astuces pour les limites de débit et les exclusions dans les requêtes de recherche.

Compatible avec~Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add MichaelYochpaz/agent-skills

Installed? Explore more Rédaction et édition skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait GitHub CLI (gh) ?

Interagissez avec GitHub depuis la ligne de commande : dépôts, versions, issues, PRs, discussions, recherche, revue de code et Actions.

Vérifié avec gh 2.95.0.

Directives pour l'agent

  • Pour les fichiers ou répertoires distants connus, utilisez gh repo read-file / gh repo read-dir (aperçu dans gh 2.95). Pour les versions antérieures de gh ou des besoins uniquement via API, utilisez l'API de contenu en repli dans API Patterns.
  • Lorsqu'une tâche nécessite de chercher dans plusieurs fichiers ou d'explorer du code inconnu dont les chemins ne sont pas connus à l'avance, clonez dans un répertoire temporaire (gh repo clone owner/repo <temp-dir> -- --depth 1) et utilisez les outils locaux de lecture et de recherche de fichiers.
  • Préférez la sortie texte par défaut à --json pour la lecture/visualisation — elle est plus économe en jetons. Utilisez --json avec --jq uniquement lorsque vous extrayez des champs spécifiques de manière programmatique. Pour découvrir les champs pris en charge, exécutez la commande avec --json sans liste de champs, puis demandez uniquement les champs dont vous avez besoin.
  • Lorsque vous consultez des logs ou des diffs, limitez d'abord la sortie (par ex., --name-only, --log-failed) avant de récupérer le contenu complet.
  • Le flag --repo est inutile lorsque vous travaillez dans un dépôt cloné — le dépôt du répertoire courant est utilisé par défaut. Pour gh api, utilisez le chemin explicite (repos/OWNER/REPO/...) ou définissez la variable d'environnement GH_REPO.
  • Utilisez cette compétence pour les workflows couverts. Si un flag ou un champ nécessaire est manquant ici, si une commande échoue avec un flag inconnu/modifié, ou si la commande est marquée comme aperçu, consultez l'aide spécifique de cette commande (par ex., gh pr diff --help).

Sécurité

  • Opérations d'écriture (create, edit, comment, review, close, merge, delete, rerun, run cancel, workflow run/enable/disable, mutations de discussion) modifient l'état GitHub. Confirmez avec l'utilisateur avant d'exécuter, en particulier sur les dépôts que vous ne possédez pas.
  • gh api avec --method POST/PUT/PATCH/DELETE envoie des requêtes d'écriture. Vérifiez doublement le point de terminaison et la charge utile. La méthode par défaut est GET (sûre) ; l'ajout des paramètres -f/-F change la méthode par défaut en POST.
  • Les opérations destructrices (delete, close, merge --admin) peuvent être irréversibles. Exigent une confirmation explicite de l'utilisateur.

Prérequis

Vérifiez que gh est installé et authentifié avant d'exécuter des commandes :

gh --version
gh auth status

Sinon, guidez l'utilisateur via gh auth login.

Flags communs

Ces flags sont disponibles sur de nombreux groupes de commandes, mais leur prise en charge varie selon la commande :

  • --repo OWNER/REPO -- Cible un dépôt différent (par défaut : le dépôt du répertoire courant). Accepte également les URL complètes.
  • --json FIELDS -- Sortie au format JSON avec les champs spécifiés. Passez sans valeur pour lister les champs disponibles.
  • --jq EXPRESSION -- Filtre la sortie JSON en utilisant la syntaxe jq. Nécessite --json.
  • --template STRING -- Formate la sortie JSON avec un template Go (alternative à --jq).
  • --web -- Ouvre la ressource dans le navigateur au lieu de l'afficher dans le terminal.
  • --limit N -- Nombre maximum de résultats pour les commandes de liste (par défaut généralement 30).

Dépôts

Voir

Affiche la description, le README, les étoiles, la répartition des langages et d'autres métadonnées d'un dépôt.

gh repo view owner/repo
gh repo view owner/repo --json name,description,defaultBranchRef,languages,stargazerCount

Cloner

Clone un dépôt localement. Configure automatiquement le remote et, pour les forks, configure le remote amont.

gh repo clone owner/repo [répertoire-cible]

Lire le contenu d'un dépôt distant

Pour des lectures rapides de fichiers ou répertoires connus, utilisez les commandes de lecture de dépôt (aperçu dans gh 2.95) :

# Fichier connu
gh repo read-file src/main.py --repo owner/repo --ref main

# Répertoire connu
gh repo read-dir src --repo owner/repo --ref main

# Repli pour les versions antérieures de gh
gh api "repos/OWNER/REPO/contents/src/main.py?ref=main" -H "Accept: application/vnd.github.raw+json"

Pour les formes de sortie, les limites de taille de fichier et les mises en garde sur le listage des répertoires, voir API Patterns. Pour l'exploration multi-fichiers, clonez plutôt (voir Directives pour l'agent).

Lister les dépôts

Liste les dépôts appartenant à un utilisateur ou une organisation, avec des filtres optionnels par langue et visibilité.

gh repo list owner --limit 30

Versions

Lister

Liste les versions dans un dépôt, triées par date de création (les plus récentes en premier). Par défaut, affiche toutes les versions, y compris les pré-versions et les brouillons.

gh release list --repo owner/repo --limit 10

Flags :

  • --exclude-pre-releases -- Exclure les pré-versions
  • --exclude-drafts -- Exclure les brouillons

Champs JSON clés : tagName, name, publishedAt, isLatest, isDraft, isPrerelease, isImmutable

Voir (journal des modifications, actifs)

Affiche le corps du journal des modifications, le tag, les actifs et les métadonnées d'une version. Omettre le tag pour voir la dernière version.

gh release view --repo owner/repo                         # Dernière version
gh release view v1.2.0 --repo owner/repo                  # Tag spécifique
gh release view v1.2.0 --json tagName,body,assets,publishedAt

Champs JSON clés : tagName, name, body, assets, author, publishedAt, isDraft, isPrerelease, isImmutable, url

Issues

Lister

Liste les issues dans un dépôt, filtrées par état, label, assigné ou requête de recherche. Par défaut, affiche uniquement les issues ouvertes.

gh issue list --repo owner/repo
gh issue list --repo owner/repo --state all --label bug --assignee @me
gh issue list --repo owner/repo --search "error no:assignee sort:created-asc"

Flags :

  • --state VALUE -- open (par défaut), closed, all
  • --label NAME -- Filtrer par label (répéter pour plusieurs)
  • --assignee LOGIN -- Filtrer par assigné (@me pour soi-même)
  • --search QUERY -- Syntaxe de recherche GitHub

Champs JSON clés : number, title, state, stateReason, author, labels, assignees, createdAt, updatedAt, url

Voir

Affiche le titre, le corps, les labels, les assignés et le statut d'une issue. Utilisez --comments pour inclure le fil de commentaires complet.

gh issue view 123
gh issue view 123 --comments
gh issue view 123 --json title,body,labels,comments,state

Créer

Crée une nouvelle issue avec un titre, un corps, des labels et des assignés.

gh issue create --title "Bug: description" --body "Détails..." --label bug --assignee user1

Modifier

Met à jour le titre, le corps, les labels, les assignés ou le jalon d'une issue. Tous les flags peuvent être combinés en un seul appel.

Flags :

  • --title TEXTE / --body TEXTE -- Mettre à jour le titre ou le corps
  • --add-label NOM / --remove-label NOM -- Modifier les labels
  • --add-assignee LOGIN / --remove-assignee LOGIN -- Modifier les assignés
  • --milestone NOM / --remove-milestone -- Définir ou supprimer le jalon

Commenter

Ajoute un commentaire à une issue existante.

gh issue comment 123 --body "Texte du commentaire"

Fermer / Rouvrir

Ferme ou rouvre une issue. Optionnellement, spécifiez une raison de fermeture et laissez un commentaire.

gh issue close 123 --comment "Corrigé dans la PR #456" --reason "not planned"
gh issue close 123 --duplicate-of 456
gh issue reopen 123

Raisons de fermeture : completed (par défaut), not planned, duplicate.

Statut

Affiche un résumé des issues qui vous concernent : assignées à vous, vous mentionnant, et ouvertes par vous.

gh issue status

Pour les types d'issues, sous-issues, relations parent, dépendances bloquantes et leurs champs JSON (nécessite des hôtes GitHub compatibles), voir Issues reference.

Pull Requests

Utilisez ces commandes pour visualiser et inspecter les PRs. Pour la création, la fusion, la revue et la gestion des PRs, voir Pull Requests reference.

Lister

Liste les pull requests dans un dépôt, filtrées par état, auteur, label ou requête de recherche. Par défaut, affiche uniquement les PRs ouvertes.

gh pr list --repo owner/repo
gh pr list --repo owner/repo --state all --author @me --label "needs-review"
gh pr list --repo owner/repo --search "status:success review:required"
gh pr list --repo owner/repo --app dependabot

Flags :

  • --state VALUE -- open (par défaut), closed, merged, all
  • --draft -- Filtrer par état brouillon
  • --author LOGIN / --assignee LOGIN -- Filtrer par auteur ou assigné
  • --label NAME -- Filtrer par label
  • --search QUERY -- Syntaxe de recherche GitHub
  • --app NAME -- Filtrer par auteur GitHub App (par ex., dependabot)

Champs JSON clés : number, title, state, author, headRefName, baseRefName, labels, reviewDecision, isDraft, statusCheckRollup, files, commits, reviews, url

Voir

Affiche le titre, le corps, le statut de la revue, les vérifications et d'autres métadonnées d'une PR. Sans argument, affiche la PR pour la branche courante. Utilisez --comments pour inclure le fil de commentaires.

gh pr view 123
gh pr view 123 --comments
gh pr view 123 --json title,body,files,commits,reviews,reviewDecision

Statut

Affiche un résumé des PRs qui vous concernent : la PR de la branche courante, les PRs que vous avez créées et les PRs où votre revue est demandée.

gh pr status

Discussions

Utilisez gh discussion pour les Discussions de dépôt (aperçu dans gh 2.94). Commencez par les commandes de lecture et vérifiez les flags avec --help car l'ensemble de commandes est en aperçu :

gh discussion list --repo owner/repo --limit 10
gh discussion view 123 --repo owner/repo --comments

Pour la création, l'édition, les commentaires, les fils de réponse, les formes de sortie JSON et les modèles de repli GraphQL, voir Discussions reference.

Recherche

Recherche sur GitHub pour les issues, les PRs, le code, les commits et les dépôts. Utilisez gh issue list / gh pr list pour un seul dépôt ; utilisez gh search ... pour les requêtes multi-dépôts ou à l’échelle d’un propriétaire.

Pour la syntaxe complète des requêtes de recherche, voir la documentation de recherche GitHub. Pour les flags spécifiques à chaque sous-commande, exécutez gh search <sub-commande> --help.

Limites de débit : Les API de recherche ont des limites de débit plus strictes que l'API de base. La recherche de code est la plus restrictive (~10/min authentifié ; nécessite une authentification). Les autres commandes de recherche permettent ~30/min authentifié ou ~10/min non authentifié. Vérifiez le quota actuel avec gh api rate_limit --jq '.resources | {search, code_search}'.

Quand cloner plutôt : Voir Directives pour l'agent pour savoir quand cloner plutôt que d'utiliser l'API.

Robots et apps : Pour les auteurs GitHub App comme Dependabot, utilisez --app dependabot ; --author dependabot filtre les comptes utilisateur, pas les auteurs d'applications.

Reconnaissance : Lorsque vous explorez un dépôt inconnu, vérifiez d'abord son langage principal pour sélectionner les valeurs --extension et --language correctes :

gh repo view owner/repo --json primaryLanguage --jq '.primaryLanguage.name'

Issues

Recherchez des issues dans plusieurs dépôts en utilisant des mots-clés, des labels, un état ou une syntaxe de recherche GitHub.

gh search issues "gestion d'erreurs" --repo owner/repo
gh search issues --label bug --state open --assignee @me
gh search issues --app dependabot --repo owner/repo
gh search issues --involves username --comments ">10" --repo owner/repo

Flags clés : --repo, --owner, --state, --label, --assignee, --author, --app, --involves, --comments, --match, --sort, --include-prs.

PRs

Recherchez des pull requests dans plusieurs dépôts. Prend en charge le filtrage par auteur, statut de revue, état de fusion et statut brouillon.

gh search prs "refactor" --repo owner/repo
gh search prs --review-requested @me --state open
gh search prs --app dependabot --repo owner/repo
gh search prs --author username --merged --repo owner/repo

Flags clés : --repo, --owner, --state, --merged, --draft, --author, --assignee, --app, --label, --review, --review-requested, --base, --head, --checks, --sort.

Code

Recherche dans le contenu des fichiers sur tous les dépôts GitHub. Renvoie uniquement les lignes correspondantes (pas de numéros de ligne, pas de contexte environnant). Utile pour localiser les fichiers contenant un motif, mais suivez avec une lecture de fichier ou clonez le dépôt pour comprendre la logique du code.

Limitations : Utilise un moteur de recherche hérité (les résultats peuvent ne pas correspondre à github.com). Ne recherche que la branche par défaut. Seuls les fichiers de moins de 384 Ko sont indexés. Chaque requête doit inclure au moins un terme de recherche (les recherches par qualificateur seul comme --extension ts échoueront). Ne prend pas en charge --sort ou --order — les résultats sont toujours classés par pertinence.

gh search code "nomDeFonction" --repo owner/repo
gh search code "createServer" --repo owner/repo --extension ts
gh search code "lint" --repo owner/repo --filename package.json

Flags clés : --repo, --owner, --extension, --filename, --language, --match, --size.

Champs JSON clés : path, repository, sha, textMatches, url.

Le champ textMatches fournit un contexte de fragment avec des positions de correspondance au niveau des caractères — utilisez --json path,textMatches lorsque vous avez besoin de plus de contexte que la sortie texte par défaut.

Commits

Recherchez des commits par texte de message, auteur, date de commit ou hash.

gh search commits "correction bug" --repo owner/repo
gh search commits --author username --committer-date ">2024-01-01"
gh search commits --hash abc1234

Flags clés : --repo, --owner, --author, --committer, --author-date, --committer-date, --author-name, --author-email, --hash, --merge, --sort.

Dépôts

Recherchez des dépôts par mot-clé, langage, sujet, étoiles, licence ou propriétaire. Note : --repo n'est pas disponible sur cette sous-commande — utilisez --owner pour filtrer par propriétaire.

gh search repos "mot-clé" --language python --sort stars --order desc
gh search repos --topic cli --stars ">1000" --language go

Flags clés : --owner, --language, --topic, --stars, --forks, --license, --created, --updated, --match, --sort, --include-forks, --visibility.

Exclure des qualificateurs (préfixe trait d'union)

Les requêtes de recherche avec des exclusions comme -label:bug nécessitent une syntaxe spéciale pour éviter l'interprétation des flags du shell. Tous les flags (par ex., --limit) doivent apparaître avant -- ; tout ce qui suit -- est interprété comme le texte de la requête de recherche :

# Shells de type Unix
gh search issues -- "ma requête -label:bug"

# PowerShell
gh --% search issues -- "ma requête -label:bug"

…

[tronqué pour la traduction]

Skills associés