Compétence GitHub CLI (gh)
Utilisez gh CLI pour interagir avec les dépôts GitHub, les issues, les pull requests et les workflows GitHub Actions depuis le terminal.
Prérequis
Vérifiez que gh est installé et authentifié :
gh --version
gh auth status
S'il n'est pas authentifié, exécutez gh auth login et suivez les instructions.
Workflows principaux
Gestion des issues
# Lister les issues
gh issue list # Issues ouvertes du dépôt courant
gh issue list --state all # Toutes les issues, y compris fermées
gh issue list --assignee @me # Issues qui vous sont assignées
gh issue list --label "bug" # Filtrer par label
# Créer une issue
gh issue create -t "Titre" -b "Description"
gh issue create -t "Titre" --label "bug,priority:high" --milestone "milestone-1"
gh issue create # Mode interactif
# Voir/mettre à jour une issue
gh issue view 123 # Voir les détails de l'issue
gh issue view 123 --web # Ouvrir dans le navigateur
gh issue edit 123 --add-label "in-progress"
gh issue close 123
gh issue reopen 123
# Ajouter des commentaires
gh issue comment 123 -b "Je travaille dessus maintenant"
Workflow de branche et de commit
# Créer une branche de fonctionnalité/correction
git checkout -b feature/ma-fonctionnalite
git checkout -b fix/issue-123
git checkout -b draft/wip-experiment
# Stager et commiter les modifications
git add .
git commit -m "feat: ajouter une nouvelle fonctionnalité"
git commit -m "fix: résoudre l'issue #123"
# Pousser la branche vers le dépôt distant
git push -u origin feature/ma-fonctionnalite
Gestion des pull requests
# Créer une PR (plusieurs méthodes)
gh pr create # Mode interactif
gh pr create --fill # Remplissage automatique depuis les commits
gh pr create --draft # Créer en tant que brouillon
gh pr create --draft --fill # Brouillon avec remplissage automatique
gh pr create -t "Titre" -b "Description" -B main
gh pr create --label "review-needed" --assignee @me
# Lister les PRs
gh pr list # PRs ouvertes
gh pr list --assignee @me # Vos PRs
gh pr list --search "review-requested:@me" # PRs demandant votre revue
gh pr list --draft # Uniquement les PRs brouillons
# Voir les détails d'une PR
gh pr view 45 # Voir la PR dans le terminal
gh pr view 45 --web # Ouvrir dans le navigateur
Workflow de revue de code
# Récupérer la PR localement pour test
gh pr checkout 45 # Récupérer la branche de la PR localement
# Voir les modifications
gh pr diff 45 # Voir le diff de la PR
gh pr diff # Diff pour la PR de la branche courante
# Ajouter des commentaires de revue
gh pr comment 45 -b "LGTM, petite suggestion sur la ligne 42"
gh pr comment -b "Veuillez ajouter des tests" # Commenter la PR de la branche courante
# Soumettre une revue formelle
gh pr review 45 --approve
gh pr review 45 --request-changes -b "Veuillez corriger la gestion des erreurs"
gh pr review 45 --comment -b "Bon dans l'ensemble, quelques suggestions"
# Fusionner
gh pr merge 45 # Fusion interactive
gh pr merge 45 --squash # Fusion squash
gh pr merge 45 --rebase # Fusion rebase
gh pr merge 45 --merge # Commit de fusion standard
gh pr merge 45 --auto # Fusion automatique lorsque les vérifications passent
Mettre à jour une PR existante
gh pr edit 45 --title "Nouveau titre"
gh pr edit 45 --body "Description mise à jour"
gh pr edit 45 --base develop
gh pr edit 45 --add-label "ready-for-review"
gh pr ready 45 # Marquer comme prêt (retirer le statut brouillon)
Gestion des workflows GitHub Actions
# Lister les exécutions de workflows
gh run list # Exécutions récentes
gh run list --workflow=ci.yml # Workflow spécifique
gh run list --status=failure # Uniquement les exécutions échouées
# Voir les détails d'une exécution
gh run view # Sélecteur interactif d'exécution
gh run view 12345 # Exécution spécifique
gh run view 12345 --web # Ouvrir dans le navigateur
# Déclencher un workflow
gh workflow run ci.yml # Exécuter sur la branche par défaut
gh workflow run ci.yml --ref feature/x # Exécuter sur une branche spécifique
gh workflow run ci.yml -f key=value # Avec des paramètres d'entrée
# Relancer les jobs échoués
gh run rerun 12345 # Relancer tous les jobs
gh run rerun 12345 --failed # Relancer uniquement les jobs échoués
# Voir les logs des jobs
gh run view 12345 --log # Sortie complète des logs
gh run view 12345 --log-failed # Uniquement les logs des jobs échoués
# Regarder une exécution en cours
gh run watch # Regarder l'exécution courante
gh run watch 12345 # Regarder une exécution spécifique
Référence des flags courants
| Flag | Description |
|---|---|
-R, --repo OWNER/REPO | Cibler un dépôt différent |
-B, --base | Branche de base pour la PR |
-H, --head | Branche de tête pour la PR |
-t, --title | Titre de l'issue/PR |
-b, --body | Corps/description de l'issue/PR |
-l, --label | Labels (séparés par des virgules) |
-a, --assignee | Nom d'utilisateur de l'assigné |
-m, --milestone | Nom du jalon |
--draft | Créer en tant que PR brouillon |
--fill | Remplissage automatique des messages de commit |
--web | Ouvrir dans le navigateur |
-y, --yes | Ignorer les invites de confirmation |
Variables d'environnement
export GH_TOKEN="ghp_xxxx" # Token d'accès personnel
export GH_HOST="github.example.com" # Instance GitHub Enterprise
export GH_REPO="owner/repo" # Dépôt par défaut
Astuces et pièges
Descriptions multi-lignes avec Markdown
Lors de la création d'issues ou de PRs avec de longues descriptions contenant du markdown (blocs de code, backticks), évitez les heredocs qui peuvent échouer à cause de l'interprétation du shell. Utilisez plutôt :
# Étape 1 : Écrire la description dans un fichier temporaire (en dehors de bash)
# Étape 2 : Créer à partir du fichier temporaire
gh issue create -t "Titre" -b "$(cat temp_description.txt)"
# Étape 3 : Nettoyer
rm temp_description.txt
Cela évite les problèmes liés à :
- Les backticks dans les blocs de code en conflit avec la substitution de commande
- Les caractères spéciaux interprétés par le shell
- Les conflits de délimiteurs heredoc
Alimenter la description à partir de fichiers existants
Pour créer une issue ou une PR à partir d'un fichier de plan markdown :
# Utiliser le flag body-file pour des descriptions propres à partir de fichiers
gh issue create -t "Titre" --body-file docs/plans/mon-plan.md
gh pr create -t "Titre" --body-file docs/plans/mon-plan.md
Référence détaillée
Pour des options de commande complètes et des exemples, voir references/commands.md.