Crear extensiones del CLI de GitHub

Acerca de las extensiones del CLI de GitHub

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

Necesitas un repositorio para cada extensión que crees. El nombre de repositorio debe iniciar con gh-. El resto del nombre del repositorio es el nombre de la extensión. En la raíz del repositorio, debe haber un archivo ejecutable con el mismo nombre del repositorio. Este archivo se ejecutará cuando se invoque la extensión.

Crear una extensión con gh extension create

Puedes utilizar el comando gh extension create para crear un proyecto para tu extensión, incluyendo un script de bash que contenga algo de código de inicio.

1. Configura una extensión utilizando el subcomando gh extension create. Reemplaza EXTENSION-NAME con el nombre de tu extensión.

   gh extension create EXTENSION-NAME

2. Sigue las instrucciones impresas para finalizar y, opcionalmente, publicar tu extensíón.

Crear una extensión manualmente

1. Crea un directorio local para tu extensión llamado gh-EXTENSION-NAME. Reemplaza a EXTENSION-NAME con el nombre de tu extensión. Por ejemplo, gh-whoami.

2. En el directorio que creaste, agrega un archivo ejecutable con el mismo nombre que el directorio.

   Nota: Asegúrate de que tu archivo sea ejecutable. En Unix, puedes ejecutar chmod +x file_name en la línea de comandos para hacer ejecutable a file_name. En Windows, puedes ejecutar git init -b main, git add file_name, luego git update-index --chmod=+x file_name.

3. Escribe tu script en el archivo ejecutable. Por ejemplo:

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

4. Desde tu directorio, instala la extensión como extensión local.

   gh extension install .
   

5. Verifica que tu extensión funcione. Reemplaza a EXTENSION-NAME con el nombre de tu extensión. Por ejemplo, whoami.

   gh EXTENSION-NAME

6. Desde tu directorio, crea un repositorio para publicar tu extensión. Reemplaza a EXTENSION-NAME con el nombre de tu extensión.

   git init -b main
   gh repo create gh-EXTENSION-NAME --confirm
   git add . && git commit -m "initial commit" && git push --set-upstream origin main

7. Opcionalmente, para ayudar a que otros usuarios descubran tu extensión, agrega el tema de repositorio gh-extension. Esto hará que la extensión aparezca en la página de tema gh-extension. Para obtener más información sobre cómo agregar un tema de repositorio, consulta la sección "Clasificar tu repositorio con temas".

Tips para escribir extensiones de CLI de GitHub

Manejar argumentos y marcadores

Todos los argumentos de línea de comandos que le sigan a un comando gh my-extension-name se pasará al script de la extensión. En un script de bash, puedes referenciar argumentos con $1, $2, etc. Puedes utilizar argumentos para tomar aportaciones de los usuarios o para modificar el comportamiento del script.

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

#!/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 CLI de GitHub 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 con programación

Muchos comandos nucleares son compatibles con el marcador --json para recuperar datos con 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 nuclear para recuperar datos específicos de GitHub, puedes utilizar 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 obtener más información, consulta gh help formatting.

Pasos siguientes

Para ver más ejemplos de extensiones de CLI de GitHub, revisa el tema de repositorios con la gh-extension.