S’authentifier avec GitHub CLI

À propos de l’authentification GitHub CLI

La plupart des GitHub CLI commandes agissent en votre nom GitHub, vous devez donc vous authentifier avant de pouvoir les utiliser. GitHub CLI prend en charge plusieurs façons de s’authentifier, selon que vous travaillez de manière interactive sur votre ordinateur ou que vous exécutez des commandes dans un script ou dans un environnement automatisé.

Pour une utilisation interactive, connectez-vous une fois avec gh auth login et GitHub CLI stocke vos informations d’identification pour vous.
Pour les scripts et l’automatisation, fournissez un jeton via une variable d’environnement.
Pour les flux de travail, utilisez le jeton fourni par GitHub Actions.

Vous pouvez également opter pour des informations d’identification à expiration automatique qui s’actualisent automatiquement, ce qui réduit le risque de fuite d’un jeton.

Se connecter de manière interactive

Pour vous authentifier sur votre ordinateur, exécutez la commande suivante à partir de votre terminal.
```
gh auth login
```
Suivez les invites à l’écran pour terminer de vous connecter. Lorsqu’on vous demande où vous utilisez GitHub:
- Si vous utilisez GitHub.com, sélectionnez GitHub.com.
- Si vous utilisez un autre hôte, sélectionnez Autre, puis entrez votre nom d’hôte, par exemple octocorp.ghe.com.

Par défaut, GitHub CLI stocke vos informations d’identification dans le keyring de votre système d’exploitation lorsqu’il est disponible, et sinon dans un fichier de configuration en texte brut. Vous n’avez pas besoin de gérer ce fichier vous-même.

S’authentifier avec une variable d’environnement

Pour les scripts et d’autres utilisations non interactives, vous pouvez fournir un jeton via une variable d’environnement au lieu de vous connecter. Définir GH_TOKEN pour GitHub.com et GitHub Enterprise Cloud, ou GH_ENTERPRISE_TOKEN pour GitHub Enterprise Server.

GH_TOKEN=YOUR-TOKEN gh api user

Remplacez YOUR-TOKEN par votre jeton. Quand l’une de ces variables est définie, GitHub CLI l’utilise au lieu d’informations d’identification stockées et n’écrit pas le jeton sur le disque. Pour définir un hôte par défaut pour les commandes qui ne sont pas liées à un référentiel spécifique, définissez la variable d’environnement GH_HOST .

Authentification dans GitHub Actions

Dans un GitHub Actions flux de travail, authentifiez GitHub CLI en transmettant la valeur GH_TOKEN automatiquement fournie via la variable d’environnement GITHUB_TOKEN. Cela fonctionne pour les deux GitHub.com et GitHub Enterprise Cloud.

steps:
  - name: List open issues
    env:
      GH_TOKEN: ${{ github.token }}
    run: gh issue list --repo ${{ github.repository }}

Pour plus d’informations sur le jeton que GitHub Actions fournit, consultez GITHUB_TOKEN.

Sur GitHub Enterprise Server, définissez GH_ENTERPRISE_TOKEN au lieu de GH_HOST, et définissez GitHub Enterprise Server sur votre hôte GitHub CLI afin que GH_TOKEN s’authentifie auprès de l’instance appropriée. L’exemple suivant utilise ghes.example.com comme hôte.

steps:
  - name: List open issues
    env:
      GH_HOST: ghes.example.com
      GH_ENTERPRISE_TOKEN: ${{ github.token }}
    run: gh issue list --repo ${{ github.repository }}

S’authentifier avec Git via HTTPS

Lorsque vous choisissez HTTPS comme protocole préféré pour les opérations Git et confirmez que vous souhaitez vous authentifier auprès de Git avec vos GitHub informations d’identification, GitHub CLI il se configure en tant que gestionnaire d’identification Git si vous n’en avez pas déjà configuré. Cela vous permet d’exécuter des commandes Git telles que git push et git pull sans configurer un gestionnaire d’informations d’identification distinct ni utiliser SSH. Si vous utilisez déjà un autre assistant d’identification, GitHub CLI stocke vos nouvelles informations d’identification dans cet assistant à la place.

Vous pouvez le configurer à tout moment en exécutant la commande suivante.

gh auth setup-git

Pour configurer Git pour un seul hôte au lieu de tous les hôtes authentifiés, utilisez l’indicateur --hostname , par exemple gh auth setup-git --hostname github.com.

Utilisation de jetons expirants et actualisables

Par défaut, GitHub CLI s’authentifie avec un jeton de longue durée qui n’expire pas. Si un tel jeton est divulguée, il accorde l’accès jusqu’à ce que vous le révoquez manuellement.

Les tokens qui expirent réduisent ce risque. Lorsque vous choisissez de participer, GitHub CLI stocke un jeton d’accès arrivant à expiration avec un jeton d’actualisation à rotation. Le jeton d’accès expire en quelques heures, et GitHub CLI utilise automatiquement le jeton d’actualisation pour obtenir un nouveau jeton d’accès chaque fois qu’un nouveau jeton d’accès est nécessaire. Vous restez authentifié sans vous reconnecter, tandis qu’un jeton d’accès divulgué devient inutilisable dans les heures au lieu de rester valable indéfiniment.

Ce comportement est facultatif et compatible avec les versions antérieures. Si vous n’optez pas, rien ne change, et les connexions existantes et les jetons fournis manuellement continuent de fonctionner comme avant.

Acceptation

Les jetons arrivant à expiration nécessitent GitHub CLI la version v2.103.0 ou ultérieure.

Les jetons arrivant à expiration sont disponibles sur GitHub.com et GitHub Enterprise Cloud. Pour plus d’informations sur le fonctionnement des jetons OAuth arrivant à expiration et des jetons d’actualisation, consultez Autorisation des applications OAuth.

Pour demander des informations d’identification arrivant à expiration, ajoutez l’option --expiring lorsque vous vous connectez.

gh auth login --expiring

Le fait de recevoir des informations d’identification expirantes dépend de la prise en charge du serveur. L’indicateur --expiring en demande la récupération. Si le serveur ne les prend pas en charge, GitHub CLI revient à un jeton normal, sans expiration et affiche un message d’information.

Une fois que vous avez activé cette option, GitHub CLI actualise les informations d’authentification pour vous chaque fois que cela est nécessaire ; il n’y a donc rien de nouveau à exécuter au quotidien.

Pour activer cette option à chaque connexion sans avoir à passer le paramètre à chaque fois, activez le paramètre :

gh config set expiring_credentials enabled

Utilisation de jetons arrivant à expiration avec Git

Pour utiliser des jetons arrivant à expiration pour les opérations Git sur HTTPS, GitHub CLI doit être votre assistant d’identification Git, afin qu’il puisse fournir et actualiser les informations d’identification tournantes pour Git. Lorsque vous vous connectez avec des informations d’identification arrivant à expiration, GitHub CLI vous invite à le configurer en tant qu’assistant d’identification Git si ce n’est pas déjà fait. Pour vous assurer que GitHub CLI est configuré en tant qu’assistant à tout moment, exécutez gh auth setup-git.

Nous vous recommandons également de procéder à la mise à niveau vers Git 2.46 ou version ultérieure. Dans Git 2.46 et versions ultérieures, GitHub CLI peut marquer des informations d’identification arrivant à expiration afin qu’un assistant d’identification de mise en cache ne les stocke pas au-delà de leur durée de vie. Sur les versions antérieures de Git, GitHub CLI fonctionne toujours, mais affiche une recommandation ponctuelle de mise à niveau.

Lecture du jeton stocké

Certains scripts et extensions ont besoin du jeton utilisé par GitHub CLI, par exemple pour authentifier une requête curl ou un autre client HTTP. Pour imprimer le jeton actif, exécutez la commande suivante.

gh auth token

Pour des informations d’identification arrivant à expiration, GitHub CLI actualise le jeton d’accès si nécessaire avant de l’imprimer, de sorte que le jeton que vous recevez est valide. Pour lire le jeton d’un hôte spécifique, utilisez l’indicateur --hostname . Pour imprimer le jeton actuel sans l’actualiser, utilisez l’option --no-refresh.

Actualisation ou ajout de portées

Au fil du temps, une commande peut nécessiter des portées supplémentaires dont vos informations d’identification ne disposent pas encore.

Si vous utilisez des jetons arrivant à expiration, passez l’indicateur --expiring (ou activez le expiring_credentials paramètre) lorsque vous exécutez gh auth refresh. Sinon, la modification des portées peut remplacer vos informations d’identification arrivant à expiration par des informations d’identification qui n’expirent pas.

Pour modifier les portées de vos identifiants existants, utilisez la commande suivante.

gh auth refresh --scopes SCOPES

Remplacez SCOPES par une liste des scopes dont vous avez besoin, séparés par des virgules.

Cela est distinct de l’actualisation automatique d’un jeton arrivant à expiration, qui se produit en arrière-plan et ne modifie pas vos scopes. Consultez Utilisation des jetons arrivant à expiration et pouvant être actualisés.

Vérification de l’état de l’authentification

Pour voir les comptes auxquels vous êtes connecté, ainsi que des détails tels que l’expiration du jeton, exécutez la commande suivante.

gh auth status

Par défaut, le jeton lui-même est masqué. Lorsqu’un jeton a expiré ou arrive à expiration, gh auth status l’actualise dans le cadre du rapport d’état.

Utilisez ces options pour personnaliser le comportement de sortie et d’actualisation :

Pour inclure le jeton dans la sortie, ajoutez --show-token.
Pour la sortie lisible par l’ordinateur, utilisez --json, que vous pouvez combiner avec --show-token.
Pour signaler l’état actuel sans actualiser, ajoutez --no-refresh.

Déconnexion

Pour vous déconnecter d’un compte, exécutez la commande suivante et suivez les invites.

gh auth logout

Pour vous déconnecter d’un hôte spécifique sans être invité à en choisir un, utilisez l’indicateur --hostname , par exemple gh auth logout --hostname github.com.

Utilisation de plusieurs comptes

Vous pouvez vous authentifier auprès de plusieurs comptes et basculer entre eux avec gh auth switch. Pour plus d’informations, consultez « Utilisation de l’interface CLI GitHub sur plusieurs plateformes GitHub ».

Dans cet article