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.

Ce que vous allez apprendre

• Installer et authentifier GitHub CLI sur votre poste
• Gérer les Pull Requests : créer, lister, reviewer, merger
• Piloter GitHub Actions : déclencher, suivre et déboguer les runs
• Interroger l'API GitHub avec gh api et jq
• Automatiser des tâches dans vos workflows GitHub Actions

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

Pourquoi utiliser GitHub CLI ?

Le gain n'est pas seulement le confort : chaque action devient une commande reproductible, donc scriptable et rejouable à l'identique dans un workflow GitHub Actions. Le tableau ci-dessous met en regard le parcours dans le navigateur et la commande gh équivalente pour les quatre opérations les plus fréquentes.

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

Glissez pour voir

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

gh est un binaire unique, sans dépendance à installer à côté, distribué par les gestionnaires de paquets de chaque système. Choisissez l'onglet correspondant à votre poste : la commande installe le binaire, sa page de manuel et sa complétion shell.

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/CentOS :

sudo dnf install gh

Arch Linux :

sudo pacman -S github-cli

Avec Homebrew (toute distribution) :

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. Le dépôt officiel fournit la dernière version stable, par exemple :

gh version 2.96.0 (2026-07-02)
https://github.com/cli/cli/releases/tag/v2.96.0

Les dépôts des distributions (Debian, Ubuntu) proposent souvent une version plus ancienne : pour disposer des dernières commandes, préférez le dépôt GitHub ci-dessus ou Homebrew.

Authentification

Avant d'utiliser gh, vous devez vous authentifier auprès de GitHub : toutes les commandes passent par l'API, qui refuse les appels anonymes au-delà de quelques requêtes par heure. L'authentification définit aussi les portées (scopes) du jeton, donc ce que gh a le droit de faire : un jeton sans la portée workflow lira les runs mais ne pourra pas en déclencher.

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 : le flux navigateur suppose une session interactive, impossible sur un serveur. gh lit automatiquement la variable GH_TOKEN et s'en sert sans rien écrire sur le disque, ce qui convient à un conteneur jetable.

# 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

La famille gh pr couvre le cycle de vie complet d'une Pull Request : création, consultation, revue, récupération locale et fusion. Toutes ces commandes déduisent le dépôt et la branche courante du répertoire Git où vous vous trouvez, ce qui évite de répéter owner/repo à chaque appel.

Créer une PR

gh pr create pousse au besoin la branche courante, puis ouvre la Pull Request vers la branche par défaut du dépôt. Sans --title ni --body la commande passe en mode interactif ; --draft crée un brouillon, qui ne sollicite pas les relecteurs tant qu'il n'est pas marqué prêt.

# 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

gh pr list affiche par défaut les PR ouvertes du dépôt courant, limitées aux trente premières. Les filtres se combinent entre eux, et --search accepte la même syntaxe de recherche que l'interface web : un filtre déjà éprouvé dans le navigateur se rejoue tel quel en ligne de commande.

# 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

Sans numéro, gh pr view cible la PR associée à la branche courante et en affiche description, état et résultat des checks. La sortie --json alimente un script ou jq, tandis que --web bascule au navigateur pour le diff commenté.

# 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 récupère la branche de la PR, y compris lorsqu'elle provient d'un fork, et configure le suivi de la branche distante. Vous pouvez ensuite lancer les tests, ajouter un commit et le pousser sur la branche d'origine si l'auteur a autorisé les mainteneurs à modifier sa PR.

gh pr checkout 42

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

Merger une PR

gh pr merge demande la fusion à GitHub, qui applique les règles de protection de branche : la commande échoue s'il manque une revue ou un check obligatoire, elle ne force jamais le passage. --squash et --rebase remplacent ponctuellement le mode configuré sur le dépôt, et --delete-branch supprime la branche distante ainsi que sa copie locale.

# 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

gh pr review soumet une revue formelle, pas un simple commentaire : l'approbation débloque la fusion sur un dépôt qui exige des relecteurs, et --request-changes la bloque jusqu'à ce qu'une nouvelle revue lève la demande. GitHub refuse qu'un auteur relève sa propre PR : dans ce cas, seule gh pr comment fonctionne.

# 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. Deux familles de commandes se partagent le travail : gh workflow manipule les définitions (lister, activer, déclencher) et gh run manipule les exécutions (suivre, lire les logs, relancer, annuler). Ensemble, elles remplacent l'onglet Actions pour tout le diagnostic courant.

Lister les workflows

gh workflow list énumère les fichiers de .github/workflows/ reconnus par GitHub, avec leur état (active ou disabled) et leur identifiant numérique. Cet identifiant est celui à privilégier dans un script : il survit au renommage du fichier, contrairement au nom du workflow.

# 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

gh workflow run ne fonctionne que sur un workflow déclarant le déclencheur workflow_dispatch : sans lui, GitHub rejette l'appel. Les paramètres déclarés dans inputs: se passent avec -f cle=valeur, et --ref choisit la branche ou le tag sur lequel la définition du workflow sera lue.

# 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

gh run list mélange par défaut toutes les branches et tous les workflows, de l'exécution la plus récente à la plus ancienne : sur un dépôt actif, les filtres --workflow et --status sont indispensables pour retrouver quelque chose. C'est ici que vous récupérez l'identifiant attendu par gh run view, rerun et cancel.

# 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

L'option --log déverse les logs complets dans le terminal, où grep les traite bien plus vite que le déroulé de l'interface web, et --job restreint la sortie à un seul job. gh run watch suit une exécution en cours et rend la main à sa terminaison, avec un code de sortie non nul en cas d'échec.

# 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

gh run rerun relance l'exécution sur le même commit, ce qui évite le commit vide de complaisance. --failed ne rejoue que les jobs en échec et leurs dépendants, un gain considérable sur une matrice large, et --debug active la journalisation détaillée du runner.

# 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

L'annulation n'est pas instantanée : GitHub interrompt les jobs proprement, et les steps marqués if: always() s'exécutent quand même. Le run se termine avec le statut cancelled, distinct de failure dans les filtres et les badges.

gh run cancel 12345678

Télécharger les artifacts

gh run download extrait chaque artefact du run dans un dossier portant son nom, -n n'en récupérant qu'un seul. Passé le délai de rétention configuré sur le dépôt, les artefacts sont détruits et la commande échoue.

# 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

La famille gh issue reprend la mécanique de gh pr : dépôt déduit du répertoire courant, création, filtrage et mise à jour. Son intérêt principal est d'ouvrir un ticket au moment exact où vous constatez le problème, sans interrompre ce que vous étiez en train de faire dans le terminal.

Créer une issue

Sans argument, gh issue create ouvre votre éditeur pour le corps du ticket, puis propose les labels et assignés définis sur le dépôt. La valeur @me désigne le compte authentifié, ce qui évite de coder en dur un identifiant dans un script.

# 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

Répéter --label applique un ET logique : l'exemple ci-dessous ne retourne que les tickets portant les deux étiquettes à la fois. Pour les critères que les options ne couvrent pas, dates ou texte libre, --search accepte la syntaxe de recherche GitHub complète.

# 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

Toutes ces commandes prennent le numéro du ticket en argument. gh issue edit est celle qui sert en automatisation : elle ajoute ou retire labels et assignés sans toucher au titre ni au corps, donc sans écraser le travail des autres.

# 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

La famille gh repo traite le dépôt comme un objet GitHub : création, fork, clonage et consultation des métadonnées. Elle s'appuie sur git pour les opérations locales, mais gère en plus ce que git ignore complètement, comme la visibilité du dépôt ou le lien entre un fork et son dépôt d'origine.

Créer un repo

Avec --source=., gh repo create rattache le dépôt Git local existant au dépôt distant qu'il vient de créer, en configurant le remote origin ; --push envoie la branche courante dans la foulée. En mode non interactif, la visibilité (--public ou --private) est obligatoire.

# 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

gh repo clone accepte la notation courte owner/repo et applique le protocole choisi lors de gh auth login. Sur un dépôt que vous avez forké, il ajoute en prime le remote upstream vers l'original, l'étape qu'on oublie en clonant avec git et sans laquelle le fork ne se resynchronise pas.

# Clone standard
gh repo clone owner/repo

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

Fork

Lancée depuis un clone existant, la commande propose de repointer le remote origin vers votre fork et de conserver le dépôt d'origine en upstream. Lancée hors d'un dépôt, elle se contente de créer la copie sur votre compte.

# Fork dans votre compte
gh repo fork owner/repo

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

Voir un repo

gh repo view rend le README directement dans le terminal, avec la description et les sujets du dépôt : de quoi jauger un projet inconnu, une action du Marketplace par exemple, sans ouvrir d'onglet.

# 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 : gh api réutilise le jeton déjà configuré, pose les en-têtes d'authentification et de version d'API, puis retourne le JSON brut. C'est la porte de sortie quand une fonctionnalité n'a pas de commande dédiée, ou quand vous avez besoin d'un champ que gh pr view n'affiche pas. En contrepartie, vous perdez la mise en forme et les valeurs par défaut : le dépôt doit être nommé explicitement dans le chemin.

Requêtes simples

Le chemin passé à gh api est relatif à https://api.github.com, inutile de répéter le domaine, et la méthode par défaut est GET. La réponse est la représentation complète de la ressource, souvent plusieurs dizaines de champs, d'où le filtrage montré juste après.

# 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

L'option --jq applique un filtre jq à l'intérieur de gh : le binaire jq n'a pas besoin d'être installé sur la machine, ce qui compte sur un runner minimal. La sortie devient du texte ligne à ligne, directement consommable par une boucle shell, au lieu du JSON complet.

# 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

Dès qu'un champ -f est présent, gh api bascule automatiquement en POST : inutile de préciser la méthode, -X ne sert que pour PATCH ou DELETE. Chaque -f envoie une chaîne ; pour un nombre ou un booléen, utilisez -F, sinon l'API rejette la requête.

# 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

L'API GitHub répond par pages de 30 éléments par défaut, 100 au maximum : sans --paginate, un script qui compte les issues d'un gros dépôt en oublie silencieusement la majorité. L'option enchaîne les appels et concatène les pages, au prix d'autant de requêtes décomptées de votre quota horaire.

# 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. Il ne s'authentifie pas tout seul pour autant : chaque step qui l'appelle doit recevoir GH_TOKEN dans son bloc env:, et le job doit demander la permission correspondant à l'action (pull-requests: write pour commenter, contents: write pour publier une release). Cette combinaison remplace la plupart des actions tierces qui ne font qu'un appel d'API.

Commenter une PR automatiquement

Ce workflow poste un message d'accueil à l'ouverture d'une PR. Deux détails le rendent sûr : le job réclame la seule permission dont gh pr comment a besoin, pull-requests: write, et le numéro de PR transite par un bloc env: au lieu d'être interpolé dans run:, ce qui écarte toute injection de template.

name: Comment on PR

on:
  pull_request:
    types: [opened]

# Aucun droit par défaut : le job demande le minimum
permissions: {}

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

Créer une release automatique

Déclenché par la poussée d'un tag v*, ce workflow publie la release correspondante. L'option --generate-notes demande à GitHub de composer les notes de version à partir des PR fusionnées depuis le tag précédent : plus de changelog à tenir à la main. La permission contents: write est ici indispensable, une release modifie le dépôt.

name: Release

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

# Aucun droit par défaut : le job demande le minimum
permissions: {}

jobs:
  release:
    runs-on: ubuntu-24.04
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

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

Déclencher un workflow de déploiement

Ce step chaîne deux workflows : celui qui construit déclenche celui qui déploie, en lui transmettant l'environnement et le SHA à publier. Le GITHUB_TOKEN suffit, car workflow_dispatch fait partie des rares déclencheurs insensibles à la protection anti-récursion de GitHub, qui empêche sinon un workflow d'en déclencher un autre. Le workflow appelé doit déclarer les mêmes inputs: que ceux passés avec -f.

- 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

Ce step bloque tant que la CI n'est pas terminée : la commande imbriquée récupère l'identifiant du run le plus récent du workflow visé, puis gh run watch le suit jusqu'à son issue. Le code de sortie est non nul si le run échoue, ce qui fait échouer le step appelant sans écrire la moindre boucle d'attente.

- 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 : ce sont des dépôts GitHub dont le nom commence par gh-, que la CLI installe et expose comme des sous-commandes supplémentaires. Elles s'exécutent avec votre jeton et vos droits : traitez-les comme une action du Marketplace, en regardant qui les maintient avant de les installer.

Lister les extensions disponibles

Cette commande ouvre une interface en mode texte et exige donc un terminal interactif : dans un script ou en CI, passez directement par gh extension install avec le nom du dépôt.

gh extension browse

Installer une extension

L'installation se fait par dépôt, sous la forme proprietaire/nom, et la sous-commande devient disponible immédiatement. Les extensions ne se mettent pas à jour toutes seules : gh extension upgrade --all s'en charge.

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

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

Extensions populaires

Ces quatre extensions couvrent les besoins récurrents : revue quotidienne des PR, assistance en ligne de commande, ménage des branches fusionnées et génération de notes de version. Aucune n'est maintenue par GitHub, à l'exception de gh-copilot : la vigilance décrite plus haut s'applique.

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

Glissez pour voir

Configuration

gh lit ses préférences dans un fichier YAML unique et propose gh config set pour le modifier sans l'éditer à la main. Deux réglages changent réellement le confort au quotidien : l'éditeur ouvert pour rédiger les corps de PR et d'issue, et les alias, qui raccourcissent les commandes que vous tapez dix fois par jour.

Fichier de configuration

La configuration est stockée dans ~/.config/gh/config.yml : ce fichier est versionnable et se recopie tel quel d'un poste à l'autre. Il ne contient aucun secret, le jeton d'authentification vivant à part dans hosts.yml ou dans le trousseau du système.

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 : gh alias set écrit l'alias dans le fichier de configuration, il vaut donc pour tous vos dépôts. Les arguments que vous passez à l'alias sont ajoutés à la fin de la commande étendue, ce qui permet d'écrire gh co 42. gh alias list affiche les alias déjà définis.

# 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

À défaut de réglage, gh suit la variable d'environnement EDITOR. L'option --wait est obligatoire avec un éditeur graphique comme VS Code : sans elle, la commande rend la main immédiatement et gh récupère un corps de message vide.

gh config set editor "code --wait"

Dépannage

La quasi-totalité des échecs de gh remonte à l'authentification : jeton absent, expiré, ou dont les portées ne couvrent pas l'action demandée. Le message d'erreur de l'API reste souvent générique, il ne nomme pas la portée manquante. Commencez donc systématiquement par gh auth status avant de chercher ailleurs.

"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

Derrière un proxy d'entreprise, gh suit les variables HTTPS_PROXY et NO_PROXY comme la plupart des outils réseau. Si le proxy inspecte le trafic chiffré, il présente son propre certificat : ajoutez son autorité de certification au magasin de confiance du système, faute de quoi chaque commande échoue sur une erreur TLS et non sur une erreur d'authentification.

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

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À 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

FAQ

Ces questions reviennent systématiquement à l'installation et lors des premiers usages, en particulier sur la frontière entre git et gh et sur l'authentification hors du poste de travail.

Quelle est la différence entre `gh` et `git` ?

git gère votre dépôt en local (commits, branches, historique). gh dialogue avec la plateforme GitHub : Pull Requests, issues, releases, GitHub Actions, API. Les deux sont complémentaires : gh s'appuie sur git pour les opérations locales.

Faut-il installer git pour utiliser gh ?

Oui pour les commandes qui manipulent un dépôt local (gh pr checkout, gh repo clone) : gh appelle git en arrière-plan. Installez git s'il n'est pas déjà présent.

Comment se connecter sans navigateur, sur un serveur ou en CI ?

Utilisez un token plutôt que le flux navigateur : gh auth login --with-token < token.txt, ou définissez la variable d'environnement GH_TOKEN. Dans un workflow GitHub Actions, GH_TOKEN: ${{ github.token }} suffit.

Comment gérer plusieurs comptes GitHub avec gh ?

Connectez chaque compte avec gh auth login, puis basculez avec gh auth switch. La commande gh auth status affiche à tout moment le compte actif.

gh fonctionne-t-il avec GitHub Enterprise Server ?

Oui : gh auth login --hostname github.mon-entreprise.com cible une instance Enterprise Server au lieu de github.com.

Pour aller plus loin

• actionlint : Le linter qui valide la syntaxe d'un workflow avant que gh workflow run ne le déclenche pour rien.

×

📖 Voir la documentation →