# Criando extensões da CLI GitHub Aprenda a compartilhar novos comandos GitHub CLI com outros usuários criando extensões personalizadas para GitHub CLI. ## Sobre extensões de GitHub CLI As extensões de GitHub CLI são comandos de GitHub CLI personalizados que qualquer um pode criar e usar. Para obter mais informações sobre como usar extensões GitHub CLI , consulte [Usando extensões da CLI GitHub](/pt/github-cli/github-cli/using-github-cli-extensions). É necessário um repositório para cada extensão que você criar. O nome do repositório precisa começar com `gh-`. A parte restante do nome do repositório é o nome da extensão. O repositório deve ter um arquivo executável na sua raiz com o mesmo nome que o repositório ou um conjunto de executáveis binários pré-compilados anexados a uma versão. > \[!NOTE] > Ao usar um script executável, recomendamos o uso de um script do Bash, porque o Bash é um interpretador amplamente disponível. Você pode usar scripts que não são de bash, mas o usuário deverá ter o intérprete necessário instalado para usar a extensão. Se você preferir não confiar que os usuários têm intérpretes instalados, considere uma extensão pré-compilada. ## Como criar uma extensão interpretada com `gh extension create` > \[!NOTE] > Executar `gh extension create` sem argumentos iniciará um assistente interativo. Você pode usar o comando `gh extension create` para criar um project para sua extensão, incluindo um script bash que contém algum código inicial. 1. Configure uma nova extensão usando o subcomando `gh extension create`. Substitua `EXTENSION-NAME` pelo nome da extensão. ```shell gh extension create EXTENSION-NAME ``` 2. Siga as instruções impressas para finalizar e, opcionalmente, publicar sua extensão. ## Como criar uma extensão pré-compilada no Go com `gh extension create` Você pode usar o argumento `--precompiled=go` para criar um projeto baseado em Go para sua extensão, incluindo a estrutura em Go, a estrutura de fluxo de trabalho e o código inicial. 1. Configure uma nova extensão usando o subcomando `gh extension create`. Substitua `EXTENSION-NAME` pelo nome da extensão e especifique `--precompiled=go`. ```shell gh extension create --precompiled=go EXTENSION-NAME ``` 2. Siga as instruções impressas para finalizar e, opcionalmente, publicar sua extensão. ## Como criar uma extensão pré-compilada que não é do Go com `gh extension create` Você pode usar o argumento `--precompiled=other` para criar um projeto para sua extensão pré-compilada não Go, incluindo estruturação de fluxo de trabalho. 1. Configure uma nova extensão usando o subcomando `gh extension create`. Substitua `EXTENSION-NAME` pelo nome da extensão e especifique `--precompiled=other`. ```shell gh extension create --precompiled=other EXTENSION-NAME ``` 2. Adicione um código inicial para sua extensão na linguagem compilada escolhida. 3. Preencha `script/build.sh` com o código para compilar a extensão e verificar se ela pode ser compilada automaticamente. 4. Siga as instruções impressas para finalizar e, opcionalmente, publicar sua extensão. ## Criando uma extensão interpretada manualmente 1. Crie um diretório local chamado `gh-EXTENSION-NAME` para a extensão. Substitua `EXTENSION-NAME` pelo nome da extensão. Por exemplo, `gh-whoami`. 2. No diretório que você criou, adicione um arquivo executável com o mesmo nome do diretório. > \[!NOTE] > Verifique se o arquivo é executável. No UNIX, você pode executar `chmod +x file_name` na linha de comando para tornar `file_name` executável. No Windows, você pode executar `git init -b main`, `git add file_name` e depois `git update-index --chmod=+x file_name`. 3. Escreva seu script no arquivo executável. Por exemplo: ```bash #!/usr/bin/env bash set -e exec gh api user --jq '"You are @\(.login) (\(.name))."' ``` 4. No seu diretório, instale a extensão como uma extensão local. ```shell gh extension install . ``` 5. Verifique se sua extensão funciona. Substitua `EXTENSION-NAME` pelo nome da extensão. Por exemplo, `whoami`. ```shell gh EXTENSION-NAME ``` 6. No seu diretório, crie um repositório para publicar a sua extensão. Substitua `EXTENSION-NAME` pelo nome da extensão. ```shell git init -b main git add . && git commit -m "initial commit" gh repo create gh-EXTENSION-NAME --source=. --public --push ``` 7. Opcionalmente, para ajudar outros usuários a descobrir sua extensão, adicione o tópico do repositório `gh-extension`. Isso fará com que a extensão apareça na página de tópicos [`gh-extension`](https://github.com/topics/gh-extension). Para saber mais sobre como adicionar um tópico de repositório, confira [Classificar repositório com tópicos](/pt/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics). ## Dicas para escrever extensões de GitHub CLI interpretadas ### Manipulando argumentos e sinalizadores Todos os argumentos de linha de comando após um comando `gh my-extension-name` serão transmitidos para o script de extensão. Em um script do Bash, você pode referenciar argumentos com `$1`, `$2` etc. Use argumentos para usar a entrada de usuário ou modificar o comportamento do script. Por exemplo, este script manipula vários sinalizadores. Quando o script é chamado com o sinalizador `-h` ou `--help`, o script imprime o texto de ajuda em vez de continuar a execução. Quando o script é chamado com o sinalizador `--name`, o script define o próximo valor após o sinalizador como `name_arg`. Quando o script é chamado com o sinalizador `--verbose`, o script imprime outra saudação. ```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 ``` ### Chamar comandos do núcleo em modo não interativo Alguns comandos principais de GitHub CLI solicitarão ao usuário uma entrada. Ao escrever scripts com esses comandos, um prompt geralmente é indesejável. Para evitar a instrução, forneça a informação necessária explicitamente por meio de argumentos. Por exemplo, para criar um problema de modo programático, especifique o título e o texto: ```shell gh issue create --title "My Title" --body "Issue description" ``` ### Buscando dados programaticamente Muitos comandos básicos dão suporte ao sinalizador `--json` para a busca de dados por meio de programação. Por exemplo, para retornar um objeto JSON listando o número, título e status de mesclabilidade dos pull requests: ```shell gh pr list --json number,title,mergeStateStatus ``` Se não houver um comando principal para buscar dados específicos do GitHub, você poderá usar o comando [`gh api`](https://cli.github.com/manual/gh_api) para acessar a API do GitHub. Por exemplo, para obter informações sobre o usuário atual: ```shell gh api user ``` Todos os comandos que geram dados JSON de saída também têm opções para filtrar esses dados em algo mais diretamente utilizável por scripts. Por exemplo, para obter o nome do usuário atual: ```shell gh api user --jq '.name' ``` Para obter mais informações, consulte [`gh help formatting`](https://cli.github.com/manual/gh_help_formatting). ## Criando uma extensão pré-compilada manualmente 1. Crie um diretório local chamado `gh-EXTENSION-NAME` para a extensão. Substitua `EXTENSION-NAME` pelo nome da extensão. Por exemplo, `gh-whoami`. 2. No diretório que você criou, adicione um código-fonte. Por exemplo: ```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. No seu diretório, instale a extensão como uma extensão local. ```shell gh extension install . ``` 4. Construa o seu código. Por exemplo, com o Go, substituindo `YOUR-USERNAME` pelo nome de usuário GitHub: ```shell go mod init github.com/YOUR-USERNAME/gh-whoami go mod tidy go build ``` 5. Verifique se sua extensão funciona. Substitua `EXTENSION-NAME` pelo nome da extensão. Por exemplo, `whoami`. ```shell gh EXTENSION-NAME ``` 6. No seu diretório, crie um repositório para publicar a sua extensão. Substitua `EXTENSION-NAME` pelo nome da extensão. > \[!NOTE] > Tenha cuidado para não fazer confirmação do binário produzido pela etapa de compilação para o controle de versão. ```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. Crie uma versão com o objetivo de compartilhar sua extensão pré-compilada com outras pessoas. Faça a compilação para cada plataforma que você deseja suportar, anexando cada binário a uma versão como um ativo. Os executáveis binários anexados às versões precisam seguir uma convenção de nomenclatura e ter o sufixo OS-ARCHITECTURE\[EXTENSION]. Por exemplo, uma extensão chamada `whoami` compilada para o Windows de 64 bits terá o nome `gh-whoami-windows-amd64.exe`, enquanto a mesma extensão compilada para o Linux de 32 bits terá o nome `gh-whoami-linux-386`. Para ver uma lista completa de combinações de sistema operacional e arquitetura reconhecidas por `gh`, consulte [te código-fonte](https://github.com/cli/cli/blob/14f704fd0da58cc01413ee4ba16f13f27e33d15e/pkg/cmd/extension/manager.go#L696). > \[!NOTE] > Para que sua extensão seja executada corretamente no Windows, o arquivo de recursos precisa ter uma extensão `.exe`. Não é necessária qualquer extensão para outros sistemas operacionais. As liberações podem ser criadas a partir da linha de comando. Por exemplo: ```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](/pt/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).