GitHub CLI (gh) : gérer GitHub depuis le terminal

Vous êtes en train de coder, vous voulez créer une PR, vérifier le statut d’un workflow ou lire les commentaires d’une issue. Traditionnellement, vous devez quitter votre terminal, ouvrir le navigateur, naviguer jusqu’au bon endroit…

GitHub CLI (gh) vous permet de faire tout cela sans quitter le terminal. Créer des PRs, déclencher des workflows, gérer les issues — tout est accessible en ligne de commande.

Qu’est-ce que GitHub CLI ?

GitHub CLI est l’outil officiel de GitHub pour interagir avec la plateforme depuis le terminal. Il ne remplace pas Git (qui gère le code), mais complète votre workflow avec les fonctionnalités spécifiques à GitHub :

• Pull requests
• Issues
• GitHub Actions (workflows, runs)
• Releases
• Gists
• Repositories (création, fork, clone)
• Code Spaces
• Et bien plus

Analogie

Si Git est votre boîte à outils pour gérer le code, GitHub CLI est la télécommande qui pilote tout ce qui se passe sur GitHub.com — sans ouvrir le navigateur.

Pourquoi utiliser GitHub CLI ?

Tâche	Sans gh	Avec gh
Créer une PR	Navigateur → New PR → Remplir formulaire	gh pr create
Voir le statut CI	Onglet Actions → Cliquer sur le run	gh run list
Merger une PR	Navigateur → Bouton Merge	gh pr merge
Déclencher un workflow	Actions → Run workflow → Cliquer	gh workflow run

Avantages clés :

• Rapidité : pas de changement de contexte
• Scriptable : automatisez avec des scripts shell
• Cohérence : même workflow sur tous vos projets
• Intégration CI : utilisable dans les workflows GitHub Actions

Installation

macOS

Avec Homebrew :

brew install gh

Linux

Debian/Ubuntu :

# Ajouter le repository GitHub
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null

# Installer
sudo apt update
sudo apt install gh

Fedora/RHEL :

sudo dnf install gh

Avec Homebrew :

brew install gh

Windows

Avec winget :

winget install GitHub.cli

Avec Chocolatey :

choco install gh

Avec Scoop :

scoop install gh

Vérification de l’installation :

gh --version

La commande doit afficher la version installée (ex: gh version 2.67.0).

Authentification

Avant d’utiliser gh, vous devez vous authentifier auprès de GitHub :

gh auth login

Un assistant interactif vous guide :

1. Où voulez-vous vous authentifier ?

   • GitHub.com (option par défaut)
   • GitHub Enterprise Server

2. Quel protocole préférez-vous pour Git ?

   • HTTPS (recommandé)
   • SSH

3. Comment voulez-vous vous authentifier ?

   • Via navigateur (le plus simple)
   • Avec un token d’accès personnel

Si vous choisissez “navigateur”, gh ouvre une page où vous autorisez l’accès.

Vérification de l’authentification :

gh auth status

Exemple de sortie :

github.com
  ✓ Logged in to github.com account your-username
  ✓ Git operations configured with https protocol
  ✓ Token: gho_************************************
  ✓ Token scopes: gist, read:org, repo, workflow

Authentification dans les scripts

Pour les scripts ou la CI, utilisez un token :

# Via variable d'environnement
export GH_TOKEN=ghp_xxxxxxxxxxxx
gh api user

# Ou en passant le token
gh auth login --with-token < token.txt

Dans GitHub Actions, le GITHUB_TOKEN est automatiquement disponible :

- name: Liste des PRs
  run: gh pr list
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Gestion des Pull Requests

Créer une PR

# Interactif : gh pose des questions
gh pr create

# En une ligne
gh pr create --title "Add feature X" --body "Description de la PR"

# Avec labels et reviewers
gh pr create --title "Fix bug" --label "bug" --reviewer "alice,bob"

# PR en draft
gh pr create --draft --title "WIP: New feature"

Lister les PRs

# PRs ouvertes
gh pr list

# PRs avec filtres
gh pr list --state all              # Toutes (open, closed, merged)
gh pr list --author "@me"           # Mes PRs
gh pr list --label "bug"            # Par label
gh pr list --search "is:open draft:false"  # Recherche avancée

Voir une PR

# Afficher les détails
gh pr view 42

# Dans le navigateur
gh pr view 42 --web

# Au format JSON (pour scripts)
gh pr view 42 --json title,state,reviews

Checkout une PR

Pratique pour tester le code d’une PR localement :

gh pr checkout 42

Cela crée une branche locale avec le code de la PR.

Merger une PR

# Merge standard
gh pr merge 42

# Squash merge
gh pr merge 42 --squash

# Rebase merge
gh pr merge 42 --rebase

# Supprimer la branche après merge
gh pr merge 42 --delete-branch

Review une PR

# Approuver
gh pr review 42 --approve

# Demander des changements
gh pr review 42 --request-changes --body "Il faudrait corriger X"

# Commenter sans approuver
gh pr review 42 --comment --body "Bonne approche !"

GitHub Actions avec gh

gh est particulièrement utile pour gérer les workflows GitHub Actions.

Lister les workflows

# Voir les workflows du repo
gh workflow list

# Exemple de sortie :
# NAME              STATE   ID
# CI                active  12345678
# Deploy            active  12345679
# Security Scan     active  12345680

Déclencher un workflow

# Déclencher un workflow manuel (workflow_dispatch)
gh workflow run ci.yml

# Avec des inputs
gh workflow run deploy.yml -f environment=staging -f version=1.2.3

# Sur une branche spécifique
gh workflow run ci.yml --ref feature-branch

Voir les runs

# Derniers runs
gh run list

# Runs d'un workflow spécifique
gh run list --workflow ci.yml

# Runs en cours
gh run list --status in_progress

# Runs échoués
gh run list --status failure

Détails d’un run

# Voir un run spécifique
gh run view 12345678

# Voir les logs
gh run view 12345678 --log

# Logs d'un job spécifique
gh run view 12345678 --log --job 98765432

# Suivre en temps réel
gh run watch 12345678

Re-exécuter un run

# Re-run complet
gh run rerun 12345678

# Re-run uniquement les jobs échoués
gh run rerun 12345678 --failed

# Re-run avec debug activé
gh run rerun 12345678 --debug

Annuler un run

gh run cancel 12345678

Télécharger les artifacts

# Lister les artifacts d'un run
gh run view 12345678 --json artifacts

# Télécharger tous les artifacts
gh run download 12345678

# Télécharger un artifact spécifique
gh run download 12345678 -n build-output

Gestion des Issues

Créer une issue

# Interactif
gh issue create

# En une ligne
gh issue create --title "Bug: crash on login" --body "Description..."

# Avec labels et assignee
gh issue create --title "Feature request" --label "enhancement" --assignee "@me"

Lister et filtrer

# Issues ouvertes
gh issue list

# Mes issues
gh issue list --assignee "@me"

# Par label
gh issue list --label "bug" --label "priority:high"

# Recherche
gh issue list --search "is:open label:bug created:>2024-01-01"

Gérer une issue

# Voir
gh issue view 123

# Commenter
gh issue comment 123 --body "Je prends ce bug !"

# Fermer
gh issue close 123

# Rouvrir
gh issue reopen 123

# Éditer
gh issue edit 123 --add-label "in-progress" --add-assignee "alice"

Gestion des repositories

Créer un repo

# Interactif
gh repo create

# Nouveau repo public
gh repo create my-project --public

# Nouveau repo privé avec description
gh repo create my-project --private --description "Mon super projet"

# Créer depuis le répertoire courant
gh repo create --source=. --public --push

Cloner

# Clone standard
gh repo clone owner/repo

# Clone dans un dossier spécifique
gh repo clone owner/repo ./my-folder

Fork

# Fork dans votre compte
gh repo fork owner/repo

# Fork et clone
gh repo fork owner/repo --clone

Voir un repo

# Infos sur le repo courant
gh repo view

# Infos sur un autre repo
gh repo view owner/repo

# Dans le navigateur
gh repo view --web

L’API GitHub avec gh

gh peut appeler n’importe quel endpoint de l’API GitHub :

Requêtes simples

# Votre profil
gh api user

# Un repo spécifique
gh api repos/owner/repo

# Les PRs d'un repo
gh api repos/owner/repo/pulls

Avec jq pour filtrer

# Noms des branches
gh api repos/owner/repo/branches --jq '.[].name'

# Titre et état des PRs
gh api repos/owner/repo/pulls --jq '.[] | {title, state}'

Voir le guide jq pour le filtrage JSON.

Requêtes POST

# Créer un commentaire sur une issue
gh api repos/owner/repo/issues/123/comments \
  -f body="Commentaire via API"

# Créer un label
gh api repos/owner/repo/labels \
  -f name="priority:critical" \
  -f color="FF0000"

Pagination

# Toutes les pages de résultats
gh api repos/owner/repo/issues --paginate --jq '.[].title'

Utilisation dans GitHub Actions

gh est préinstallé sur les runners GitHub. Utilisez-le pour des tâches automatisées.

Commenter une PR automatiquement

name: Comment on PR

on:
  pull_request:
    types: [opened]

permissions:
  pull-requests: write

jobs:
  comment:
    runs-on: ubuntu-24.04
    steps:
      - name: Add welcome comment
        run: |
          gh pr comment ${{ github.event.pull_request.number }} \
            --body "Merci pour cette PR ! L'équipe va la reviewer sous 48h."
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Créer une release automatique

name: Release

on:
  push:
    tags: ['v*']

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Create GitHub Release
        run: |
          gh release create ${{ github.ref_name }} \
            --title "Release ${{ github.ref_name }}" \
            --generate-notes
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Déclencher un workflow de déploiement

- name: Trigger deploy workflow
  run: |
    gh workflow run deploy.yml \
      -f environment=production \
      -f version=${{ github.sha }}
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Attendre la fin d’un run

- name: Wait for checks to pass
  run: |
    gh run watch $(gh run list --workflow ci.yml --json databaseId --jq '.[0].databaseId')
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Extensions gh

gh supporte des extensions pour étendre ses fonctionnalités :

Lister les extensions disponibles

gh extension browse

Installer une extension

# Extension pour les copilotes
gh extension install github/gh-copilot

# Extension pour les dashboards
gh extension install dlvhdr/gh-dash

Extensions populaires

Extension	Description
gh-dash	Dashboard interactif pour PRs et issues
gh-copilot	Assistant IA dans le terminal
gh-poi	Nettoyer les branches mergées
gh-changelog	Générer des changelogs

Configuration

Fichier de configuration

La configuration est stockée dans ~/.config/gh/config.yml :

git_protocol: https
editor: vim
prompt: enabled
pager: less
aliases:
  co: pr checkout
  prl: pr list
  prv: pr view

Alias personnalisés

Créez des raccourcis pour les commandes fréquentes :

# Créer un alias
gh alias set prl 'pr list'
gh alias set co 'pr checkout'

# Alias avec arguments
gh alias set prw 'pr view --web'

# Utiliser l'alias
gh prl
gh co 42

Modifier l’éditeur par défaut

gh config set editor "code --wait"

Dépannage

”permission denied” ou “resource not accessible”

Symptôme : gh ne peut pas effectuer une action.

Solutions :

# Vérifier les scopes du token
gh auth status

# Se réauthentifier avec plus de permissions
gh auth refresh -s workflow,repo,admin:org

“not logged in”

Symptôme : gh demande une authentification.

Solution :

gh auth login

Problèmes de proxy

# Configurer le proxy
export HTTPS_PROXY=http://proxy.example.com:8080
gh auth login

À retenir

Efficacité

Gérez GitHub sans quitter le terminal — PRs, issues, workflows.

Scriptable

Automatisez avec des scripts shell ou dans vos workflows CI.

API complète

Accédez à toute l’API GitHub avec gh api.

Extensible

Ajoutez des extensions pour des fonctionnalités avancées.

Points clés :

1. gh auth login pour vous authentifier (une seule fois)
2. gh pr pour tout ce qui concerne les Pull Requests
3. gh run et gh workflow pour GitHub Actions
4. gh api pour accéder à n’importe quel endpoint
5. Utilisez des alias pour vos commandes fréquentes

Liens utiles

• Documentation officielle GitHub CLI ↗ — Référence complète
• GitHub CLI sur GitHub ↗ — Code source et issues
• act — Exécuter les workflows localement
• Debug des workflows — Techniques de dépannage
• jq — Filtrer les sorties JSON

×

📖 Voir la documentation →