# Creación de extensiones de la CLI de GitHub Aprende cómo compartir comandos nuevos de GitHub CLI con otros usurios creando extensiones personalizadas para GitHub CLI. ## 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 obtener más información sobre cómo usar las extensiones de GitHub CLI, consulte [Uso de extensiones de la CLI de GitHub](/es/github-cli/github-cli/using-github-cli-extensions). Necesitas un repositorio para cada extensión que crees. El nombre del repositorio debe empezar con `gh-`. El nombre restante del repositorio coincide con 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` para crear un project para la extensión, incluido un script de Bash que contenga algún código de inicio. 1. Configure una nueva extensión mediante el subcomando `gh extension create`. Reemplace `EXTENSION-NAME` por el nombre de la extensión. ```shell gh extension create EXTENSION-NAME ``` 2. 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` para crear un proyecto basado en Go para su extensión, incluyendo el andamiaje de Go, la estructuración del flujo de trabajo y el código de inicio. 1. 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`. ```shell gh extension create --precompiled=go EXTENSION-NAME ``` 2. 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` para crear un proyecto para su extensión precompilada que no sea de Go, incluida la estructura del flujo de trabajo. 1. 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`. ```shell gh extension create --precompiled=other EXTENSION-NAME ``` 2. Agrega algo de código inicial para tu extensión en el lenguaje de compilación que elijas. 3. Rellene `script/build.sh` con código para crear la extensión y asegúrese de que se pueda compilar de forma automática. 4. Sigue las instrucciones impresas para finalizar y, opcionalmente, publicar tu extensíón. ## Crear una extensión interpretada manualmente 1. 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`. 2. 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`. 3. Escribe tu script en el archivo ejecutable. Por ejemplo: ```bash #!/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. ```shell gh extension install . ``` 5. Verifica que tu extensión funcione. Reemplace `EXTENSION-NAME` por el nombre de la extensión. Por ejemplo: `whoami`. ```shell gh EXTENSION-NAME ``` 6. Desde tu directorio, crea un repositorio para publicar tu extensión. Reemplace `EXTENSION-NAME` por el nombre de la extensión. ```shell git init -b main git add . && git commit -m "initial commit" gh repo create gh-EXTENSION-NAME --source=. --public --push ``` 7. 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`](https://github.com/topics/gh-extension). Para más información sobre cómo agregar un tema de repositorio, consulta [Clasificar tu repositorio con temas](/es/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics). ## Consejos para escribir extensiones interpretadas de GitHub CLI ### Manejar argumentos y banderas 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. ```bash #!/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 principales de forma no interactiva Algunos comandos principales de GitHub CLI solicitarán al usuario que proporcione datos. Cuando se hagan scripts con estos comandos, un mensaje a menudo se considera indeseable. Para evitar solicitudes, proporciona explícitamente la información necesaria mediante argumentos. Por ejemplo, para crear una propuesta con programación, especifica el título y cuerpo: ```shell 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 fusionabilidad de los pull requests: ```shell gh pr list --json number,title,mergeStateStatus ``` Si no hay un comando principal para obtener datos específicos de GitHub, puede usar el comando [`gh api`](https://cli.github.com/manual/gh_api) para acceder a la API de GitHub. Por ejemplo, para recuperar información sobre el usuario actual: ```shell 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: ```shell gh api user --jq '.name' ``` Para obtener más información, vea [`gh help formatting`](https://cli.github.com/manual/gh_help_formatting). ## Crear una extensión precompilada manualmente 1. 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`. 2. En el directorio que creaste, agrega algo de código fuente. Por ejemplo: ```golang 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()) } ``` 3. Desde tu directorio, instala la extensión como extensión local. ```shell gh extension install . ``` 4. Compila tu código. Por ejemplo, con Go, reemplazando `YOUR-USERNAME` por el nombre de usuario de GitHub: ```shell go mod init github.com/YOUR-USERNAME/gh-whoami go mod tidy go build ``` 5. Verifica que tu extensión funcione. Reemplace `EXTENSION-NAME` por el nombre de la extensión. Por ejemplo: `whoami`. ```shell gh EXTENSION-NAME ``` 6. Desde tu directorio, crea un repositorio para publicar tu extensión. Reemplace `EXTENSION-NAME` por el nombre de la extensión. > \[!NOTE] > Evite confirmar el binario generado por el paso de compilación para el control de versiones. ```shell 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" ``` 7. 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 nombre`gh-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`, consulte [este código fuente](https://github.com/cli/cli/blob/14f704fd0da58cc01413ee4ba16f13f27e33d15e/pkg/cmd/extension/manager.go#L696). > \[!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: ```shell 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* ``` 8. 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](https://github.com/topics/gh-extension). For more information about how to add a repository topic, see [Classifying your repository with topics](/es/github/administering-a-repository/managing-repository-settings/classifying-your-repository-with-topics). ## Tips for writing precompiled GitHub CLI extensions ### Automating releases Consider adding the [gh-extension-precompile](https://github.com/cli/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](https://github.com/cli/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](https://github.com/topics/gh-extension).