Création d’extensions CLI GitHub

À propos des extensions GitHub CLI

Les extensions GitHub CLI sont des commandes GitHub CLI personnalisées que tout le monde peut créer et utiliser. Pour plus d’informations sur l’utilisation d’extensions GitHub CLI, consultez « Utilisation des extensions CLI GitHub ».

Vous avez besoin d’un référentiel pour chaque extension que vous créez. Le nom du référentiel doit commencer par gh-. Le reste du nom du référentiel est le nom de l’extension. Le référentiel doit avoir un fichier exécutable à sa racine portant le même nom que le référentiel ou un ensemble d’exécutables binaires précompilés attachés à une mise en production.

Note

Lorsque vous utilisez un script exécutable, nous vous recommandons d’utiliser un script bash, car bash est un interpréteur largement disponible. Vous pouvez utiliser des scripts non bash, mais l’utilisateur doit avoir installé l’interpréteur nécessaire pour utiliser l’extension. Si vous préférez ne pas compter sur des interpréteurs qui doivent être installés, envisagez une extension précompilée.

Création d’une extension interprétée avec `gh extension create`

Note

L’exécution de gh extension create sans argument démarre un assistant interactif.

Vous pouvez utiliser la commande gh extension create pour créer un projet pour votre extension, y compris un script bash qui contient du code de démarrage.

Configurez une nouvelle extension à l’aide de la sous-commande gh extension create. Remplacez EXTENSION-NAME par le nom de votre extension.
```
gh extension create EXTENSION-NAME
```
Suivez les instructions imprimées pour finaliser et éventuellement publier votre extension.

Création d’une extension précompilée dans Go avec `gh extension create`

Vous pouvez utiliser l’argument --precompiled=go pour créer un projet Go pour votre extension, avec notamment la génération de modèles automatique Go, la génération workflows automatique et du code de démarrage.

Configurez une nouvelle extension à l’aide de la sous-commande gh extension create. Remplacez EXTENSION-NAME par le nom de votre extension et spécifiez --precompiled=go.
```
gh extension create --precompiled=go EXTENSION-NAME
```
Suivez les instructions imprimées pour finaliser et éventuellement publier votre extension.

Création d’une extension précompilée non Go avec `gh extension create`

Vous pouvez utiliser l’argument --precompiled=other pour créer un projet pour votre extension précompilée non Go, y compris la génération de workflows automatique.

Configurez une nouvelle extension à l’aide de la sous-commande gh extension create. Remplacez EXTENSION-NAME par le nom de votre extension et spécifiez --precompiled=other.
```
gh extension create --precompiled=other EXTENSION-NAME
```
Ajoutez du code initial pour votre extension dans le langage compilé de votre choix.
Remplissez script/build.sh avec du code pour générer votre extension pour vous assurer que votre extension peut être générée automatiquement.
Suivez les instructions imprimées pour finaliser et éventuellement publier votre extension.

Création manuelle d’une extension interprétée

Créez un répertoire local appelé gh-EXTENSION-NAME pour votre extension. Remplacez EXTENSION-NAME par le nom de votre extension. Par exemple : gh-whoami.
Dans le répertoire que vous avez créé, ajoutez un fichier exécutable portant le même nom que le répertoire.

Note

Assurez-vous que votre fichier est exécutable. Sur Unix, vous pouvez exécuter chmod +x file_name dans la ligne de commande pour rendre file_name exécutable. Sur Windows, vous pouvez exécuter git init -b main, git add file_name, puis git update-index --chmod=+x file_name.

Écrivez votre script dans le fichier exécutable. Par exemple :

#!/usr/bin/env bash
set -e
exec gh api user --jq '"You are @\(.login) (\(.name))."'

À partir de votre répertoire, installez l’extension en tant qu’extension locale.
```
gh extension install .
```
Vérifiez que votre extension fonctionne. Remplacez EXTENSION-NAME par le nom de votre extension. Par exemple : whoami.
```
gh EXTENSION-NAME
```
À partir de votre répertoire, créez un référentiel pour publier votre extension. Remplacez EXTENSION-NAME par le nom de votre extension.
```
git init -b main
git add . && git commit -m "initial commit"
gh repo create gh-EXTENSION-NAME --source=. --public --push
```
Si vous le souhaitez, pour aider d’autres utilisateurs à découvrir votre extension, ajoutez la rubrique de référentiel gh-extension. Cela permet d’afficher l’extension sur la page de la rubrique gh-extension. Pour plus d’informations sur l’ajout d’une rubrique de référentiel, consultez « Classification de votre dépôt avec des rubriques ».

Conseils pour écrire des extensions GitHub CLI interprétées

Gestion des arguments et des indicateurs

Tous les arguments de ligne de commande qui suivent une commande gh my-extension-name sont passés au script d’extension. Dans un script bash, vous pouvez référencer des arguments avec $1, $2, etc. Vous pouvez utiliser des arguments pour prendre des entrées utilisateur ou modifier le comportement du script.

Par exemple, ce script gère plusieurs indicateurs. Lorsque le script est appelé avec l’indicateur -h ou --help, le script imprime le texte d’aide au lieu de poursuivre l’exécution. Lorsque le script est appelé avec l’indicateur --name, le script définit la valeur suivante après l’indicateur sur name_arg. Lorsque le script est appelé avec l’indicateur --verbose, le script imprime un message d’accueil différent.

#!/usr/bin/env bash
set -e

verbose=""
name_arg=""
while [ $# -gt 0 ]; do
  case "$1" in
  --verbose)
    verbose=1
    ;;
  --name)
    name_arg="$2"
    shift
    ;;
  -h|--help)
    echo "Add help text here."
    exit 0
    ;;
  esac
  shift
done

if [ -z "$name_arg" ]
then
  echo "You haven't told us your name."
elif [ -z "$verbose" ]
then
  echo "Hi $name_arg"
else
  echo "Hello and welcome, $name_arg"
fi

Appel de commandes de base en mode non interactif

Certaines commandes essentielles de GitHub CLI invitent l’utilisateur à saisir une entrée. Lors de l’écriture de scripts avec ces commandes, une invite est souvent indésirable. Pour éviter toute invite, fournissez les informations nécessaires explicitement par le biais d’arguments.

Par exemple, pour créer un problème par programmation, spécifiez le titre et le corps :

gh issue create --title "My Title" --body "Issue description"

Extraction de données par programme

De nombreuses commandes de base prennent en charge l’indicateur --json pour extraire des données par programme. Par exemple, pour retourner un objet JSON répertoriant le nombre, le titre et l’état de fusion des demandes de tirage :

gh pr list --json number,title,mergeStateStatus

S’il n’existe pas de commande principale pour extraire des données spécifiques à partir de GitHub, vous pouvez utiliser la commande gh api pour accéder à l’API GitHub. Par exemple, pour extraire des informations sur l’utilisateur actuel :

gh api user

Toutes les commandes qui génèrent des données JSON ont également des options pour filtrer ces données dans quelque chose de plus immédiatement utilisable par des scripts. Par exemple, pour obtenir le nom de l’utilisateur actuel :

gh api user --jq '.name'

Pour plus d’informations, consultez gh help formatting.

Création manuelle d’une extension précompilée

Créez un répertoire local appelé gh-EXTENSION-NAME pour votre extension. Remplacez EXTENSION-NAME par le nom de votre extension. Par exemple : gh-whoami.

Dans le répertoire que vous avez créé, ajoutez du code source. Par exemple :

package main
import (
  "github.com/cli/go-gh"
  "fmt"
)

func main() {
  args := []string{"api", "user", "--jq", `"You are @\(.login) (\(.name))"` }
  stdOut, _, err := gh.Exec(args...)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(stdOut.String())
}

À partir de votre répertoire, installez l’extension en tant qu’extension locale.
```
gh extension install .
```
Générez votre code. Par exemple, avec Go, en remplaçant YOUR-USERNAME par votre nom d’utilisateur GitHub :
```
go mod init github.com/YOUR-USERNAME/gh-whoami
go mod tidy
go build
```
Vérifiez que votre extension fonctionne. Remplacez EXTENSION-NAME par le nom de votre extension. Par exemple : whoami.
```
gh EXTENSION-NAME
```
À partir de votre répertoire, créez un référentiel pour publier votre extension. Remplacez EXTENSION-NAME par le nom de votre extension.

Note

Veillez à ne pas valider le binaire produit par votre étape de compilation dans le contrôle de version.
```
 git init -b main
echo "gh-EXTENSION-NAME" >> .gitignore
git add main.go go.* .gitignore && git commit -m 'Initial commit'
gh repo create "gh-EXTENSION-NAME"
```
Créez une version pour partager votre extension précompilée avec d’autres personnes. Compilez pour chaque plateforme que vous souhaitez prendre en charge, en attachant chaque fichier binaire à une version en tant que ressource. Les exécutables binaires attachés aux versions doivent suivre une convention d’affectation de noms et avoir un suffixe OS-ARCHITECTURE[EXTENSION].

Par exemple, une extension nommée whoami compilée pour Windows 64 bits aurait le nom gh-whoami-windows-amd64.exe, tandis que la même extension compilée pour Linux 32 bits aurait le nom gh-whoami-linux-386. Pour afficher une liste exhaustive de combinaisons de système d’exploitation et d’architecture reconnues par gh, consultez ce code source.

Note

Pour que votre extension s’exécute correctement sur Windows, son fichier de ressources doit avoir une extension .exe. Aucune extension n’est nécessaire pour les autres systèmes d’exploitation.

Les mises en production peuvent être créées à partir de la ligne de commande. Par exemple :
```
git tag v1.0.0
git push origin v1.0.0
GOOS=windows GOARCH=amd64 go build -o gh-EXTENSION-NAME-windows-amd64.exe
GOOS=linux GOARCH=amd64 go build -o gh-EXTENSION-NAME-linux-amd64
GOOS=darwin GOARCH=amd64 go build -o gh-EXTENSION-NAME-darwin-amd64
gh release create v1.0.0 ./*amd64*
```
Optionally, to help other users discover your extension, add the repository topic gh-extension. This will make the extension appear on the gh-extension topic page. For more information about how to add a repository topic, see "Classifying your repository with topics."

Création d’extensions CLI GitHub

Dans cet article