Crear extensiones del CLI de GitHub

Acerca de las extensiones del GitHub CLI

Las extensiones del GitHub CLI son comandos personalizados del GitHub CLI que cualquiera puede crear y utilizar. Para más información sobre cómo usar las extensiones de GitHub CLI, consulta Utilizar las extensiones del CLI de GitHub.

Necesitas un repositorio para cada extensión que crees. El nombre del repositorio debe empezar con gh-. El resto del nombre del repositorio es el nombre de la extensión. El repositorio debe tener un archivo ejecutable en su raíz con el mismo nombre del repositorio o un conjunto de archivos binarios ejecutables precompilados adjuntos a un lanzamiento.

Note

Cuando se dependa de un script ejecutable, es recomendable usar un script de bash, ya que bash es un intérprete ampliamente disponible. Puedes utilizar scripts diferentes a los de bash, pero el usuario debe tener el interprete necesario instalado para poder utilizar la extensión. Si prefieres no confiar en usuarios que tengan intérpretes instalados, considera utilizar una extensión precompilada.

Creación de una extensión interpretada con `gh extension create`

Note

Al ejecutar gh extension create sin argumentos, se iniciará un asistente interactivo.

Puede usar el comando gh extension create a fin de crear un proyecto para la extensión, incluido un script de bash que contenga algo de código de inicio.

Configure una nueva extensión mediante el subcomando gh extension create. Reemplace EXTENSION-NAME por el nombre de la extensión.
```
gh extension create EXTENSION-NAME
```
Sigue las instrucciones impresas para finalizar y, opcionalmente, publicar tu extensíón.

Creación de una extensión precompilada en Go con `gh extension create`

Puede usar el argumento --precompiled=go a fin de crear un proyecto basado en Go para la extensión, incluido el scaffolding de Go y el de flujos de trabajo, y código inicial.

Configure una nueva extensión mediante el subcomando gh extension create. Reemplace EXTENSION-NAME por el nombre de la extensión y especifique --precompiled=go.
```
gh extension create --precompiled=go EXTENSION-NAME
```
Sigue las instrucciones impresas para finalizar y, opcionalmente, publicar tu extensíón.

Creación de una extensión precompilada que no sea de Go con `gh extension create`

Puede usar el argumento --precompiled=other a fin de crear un proyecto para la extensión precompilada que no sea de Go, incluido el scaffolding de flujos de trabajo.

Configure una nueva extensión mediante el subcomando gh extension create. Reemplace EXTENSION-NAME por el nombre de la extensión y especifique --precompiled=other.
```
gh extension create --precompiled=other EXTENSION-NAME
```
Agrega algo de código inicial para tu extensión en el lenguaje de compilación que elijas.
Rellene script/build.sh con código para crear la extensión y asegúrese de que se pueda compilar de forma automática.
Sigue las instrucciones impresas para finalizar y, opcionalmente, publicar tu extensíón.

Crear una extensión interpretada manualmente

Cree un directorio local llamado gh-EXTENSION-NAME para la extensión. Reemplace EXTENSION-NAME por el nombre de la extensión. Por ejemplo: gh-whoami.
En el directorio que creaste, agrega un archivo ejecutable con el mismo nombre que el directorio.

Note

Asegúrate de que el archivo sea ejecutable. En Unix, puede ejecutar chmod +x file_name en la línea de comandos para convertir file_name en ejecutable. En Windows, puede ejecutar git init -b main, git add file_name y después git update-index --chmod=+x file_name.

Escribe tu script en el archivo ejecutable. Por ejemplo:

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

Desde tu directorio, instala la extensión como extensión local.
```
gh extension install .
```
Verifica que tu extensión funcione. Reemplace EXTENSION-NAME por el nombre de la extensión. Por ejemplo: whoami.
```
gh EXTENSION-NAME
```
Desde tu directorio, crea un repositorio para publicar tu extensión. Reemplace EXTENSION-NAME por el nombre de la extensión.
```
git init -b main
git add . && git commit -m "initial commit"
gh repo create gh-EXTENSION-NAME --source=. --public --push
```
Opcionalmente, para ayudar a que otros usuarios descubran la extensión, agregue el tema de repositorio gh-extension. Esto hará que la extensión aparezca en la página del tema gh-extension. Para más información sobre cómo agregar un tema de repositorio, consulta Clasificar tu repositorio con temas.

Tipos para escribir extensiones interpretadas de GitHub CLI

Manejar argumentos y marcadores

Todos los argumentos de línea de comandos que aparecen después de un comando gh my-extension-name se pasarán al script de la extensión. En un script de bash, puede hacer referencia a argumentos con $1, $2, etc. Puede usar argumentos para tomar la entrada de usuario o modificar el comportamiento del script.

Por ejemplo, este script maneja marcadores múltiples. Cuando se llama al script con la marca -h o --help, imprime el texto de ayuda en vez de continuar con la ejecución. Cuando se llama al script con la marca --name, el script establece el siguiente valor después de la marca en name_arg. Cuando se llama al script con la marca --verbose, imprime otro saludo.

#!/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

Llamar a los comandos de forma no interactiva

Algunos comandos nucleares de GitHub CLI pedirán la entrada del usuario. Cuando se hagan scripts con estos comandos, un mensaje a menudo se considera indeseable. Para evitar los mensajes, proporciona la información necesaria explícitamente a través de argumentos.

Por ejemplo, para crear una propuesta con programación, especifica el título y cuerpo:

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

Recuperar datos mediante programación

Muchos comandos básicos admiten la marca --json para recuperar datos mediante programación. Por ejemplo, para devolver un objeto JSON listando el número, título y estado de capacidad de fusión de las solicitudes de cambios:

gh pr list --json number,title,mergeStateStatus

Si no hay un comando básico para capturar datos específicos de GitHub, puede usar el comando gh api para acceder a la API de GitHub. Por ejemplo, para recuperar información sobre el usuario actual:

gh api user

Todos los comandos que emiten datos de JSON también tiene opciones para filtrar estos datos hacia algo más inmediatamente útil mediante scripts. Por ejemplo, para obtener el nombre del usuario actual:

gh api user --jq '.name'

Para más información, vea gh help formatting.

Crear una extensión precompilada manualmente

Cree un directorio local llamado gh-EXTENSION-NAME para la extensión. Reemplace EXTENSION-NAME por el nombre de la extensión. Por ejemplo: gh-whoami.

En el directorio que creaste, agrega algo de código fuente. Por ejemplo:

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())
}

Desde tu directorio, instala la extensión como extensión local.
```
gh extension install .
```
Compila tu código. Por ejemplo, con Go, reemplace YOUR-USERNAME por el nombre de usuario de GitHub:
```
go mod init github.com/YOUR-USERNAME/gh-whoami
go mod tidy
go build
```
Verifica que tu extensión funcione. Reemplace EXTENSION-NAME por el nombre de la extensión. Por ejemplo: whoami.
```
gh EXTENSION-NAME
```
Desde tu directorio, crea un repositorio para publicar tu extensión. Reemplace EXTENSION-NAME por el nombre de la extensión.

Note

Evita confirmar el binario generado por el paso de compilación para el control de versiones.
```
 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"
```
Crea un lanzamiento para compartir tu extensión precompilada con otros. Compila para cada plataforma con la que quieras ser compatible, adjuntando cada binario a un lanzamiento como un activo. Los ejecutables binarios adjuntos a las versiones deben seguir una convención de nomenclatura y tener un sufijo de SO-ARQUITECTURA[EXTENSIÓN].

Por ejemplo, una extensión denominada whoami compilada para Windows de 64 bits tendría el nombregh-whoami-windows-amd64.exe, mientras que la misma extensión compilada para Linux de 32 bits tendría el nombre gh-whoami-linux-386. Para ver una lista exhaustiva de combinaciones de sistema operativo y arquitectura reconocidas por gh, vea este código fuente.

Note

Para que la extensión se ejecute correctamente en Windows, su archivo de recurso debe tener una extensión .exe. No se necesita ninguna extensión para otros sistemas operativos.

Los lanzamientos pueden crearse desde la línea de comandos. Por ejemplo:
```
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.

Crear extensiones del CLI de GitHub

En este artículo