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
. ReemplaceEXTENSION-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
. ReemplaceEXTENSION-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
. ReemplaceEXTENSION-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. ReemplaceEXTENSION-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 convertirfile_name
en ejecutable. En Windows, puede ejecutargit init -b main
,git add file_name
y despuésgit 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 temagh-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. ReemplaceEXTENSION-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 nombregh-whoami-linux-386
. Para ver una lista exhaustiva de combinaciones de sistema operativo y arquitectura reconocidas porgh
, 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 thegh-extension
topic page. For more information about how to add a repository topic, see "Classifying your repository with topics."
Tips for writing precompiled GitHub CLI extensions
Automating releases
Consider adding the gh-extension-precompile action to a workflow in your project. This action will automatically produce cross-compiled Go binaries for your extension and supplies build scaffolding for non-Go precompiled extensions.
Using GitHub CLI features from Go-based extensions
Consider using go-gh, a Go library that exposes pieces of gh
functionality for use in extensions.
Next steps
To see more examples of GitHub CLI extensions, look at repositories with the gh-extension
topic.