{"meta":{"title":"Criando extensões da CLI GitHub","intro":"Saiba como compartilhar novos GitHub CLI comandos com outros usuários criando extensões personalizadas para GitHub CLI.","product":"GitHub CLI","breadcrumbs":[{"href":"/pt/enterprise-server@3.22/github-cli","title":"GitHub CLI"},{"href":"/pt/enterprise-server@3.22/github-cli/github-cli","title":"CLI GitHub"},{"href":"/pt/enterprise-server@3.22/github-cli/github-cli/creating-github-cli-extensions","title":"Criando extensões da CLI GitHub"}],"documentType":"article"},"body":"# Criando extensões da CLI GitHub\n\nSaiba como compartilhar novos GitHub CLI comandos com outros usuários criando extensões personalizadas para GitHub CLI.\n\n## Sobre GitHub CLI extensões\n\nAs 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 GitHub CLI extensões, consulte [Usando extensões da CLI GitHub](/pt/enterprise-server@3.22/github-cli/github-cli/using-github-cli-extensions).\n\nÉ 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.\n\n> \\[!NOTE]\n> 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.\n\n## Como criar uma extensão interpretada com `gh extension create`\n\n> \\[!NOTE]\n> Executar `gh extension create` sem argumentos iniciará um assistente interativo.\n\nVocê 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.\n\n1. Configure uma nova extensão usando o subcomando `gh extension create`. Substitua `EXTENSION-NAME` pelo nome da extensão.\n\n   ```shell\n   gh extension create EXTENSION-NAME\n   ```\n\n2. Siga as instruções impressas para finalizar e, opcionalmente, publicar sua extensão.\n\n## Como criar uma extensão pré-compilada no Go com `gh extension create`\n\nVocê 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.\n\n1. Configure uma nova extensão usando o subcomando `gh extension create`. Substitua `EXTENSION-NAME` pelo nome da extensão e especifique `--precompiled=go`.\n\n   ```shell\n   gh extension create --precompiled=go EXTENSION-NAME\n   ```\n\n2. Siga as instruções impressas para finalizar e, opcionalmente, publicar sua extensão.\n\n## Como criar uma extensão pré-compilada que não é do Go com `gh extension create`\n\nVocê 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.\n\n1. Configure uma nova extensão usando o subcomando `gh extension create`. Substitua `EXTENSION-NAME` pelo nome da extensão e especifique `--precompiled=other`.\n\n   ```shell\n   gh extension create --precompiled=other EXTENSION-NAME\n   ```\n\n2. Adicione um código inicial para sua extensão na linguagem compilada escolhida.\n\n3. Preencha `script/build.sh` com o código para compilar a extensão e verificar se ela pode ser compilada automaticamente.\n\n4. Siga as instruções impressas para finalizar e, opcionalmente, publicar sua extensão.\n\n## Criando uma extensão interpretada manualmente\n\n1. 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`.\n\n2. No diretório que você criou, adicione um arquivo executável com o mesmo nome do diretório.\n\n   > \\[!NOTE]\n   > 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`.\n\n3. Escreva seu script no arquivo executável. Por exemplo:\n\n   ```bash\n   #!/usr/bin/env bash\n   set -e\n   exec gh api user --jq '\"You are @\\(.login) (\\(.name)).\"'\n   ```\n\n4. No seu diretório, instale a extensão como uma extensão local.\n\n   ```shell\n   gh extension install .\n   ```\n\n5. Verifique se sua extensão funciona. Substitua `EXTENSION-NAME` pelo nome da extensão. Por exemplo, `whoami`.\n\n   ```shell\n   gh EXTENSION-NAME\n   ```\n\n6. No seu diretório, crie um repositório para publicar a sua extensão. Substitua `EXTENSION-NAME` pelo nome da extensão.\n\n   ```shell\n   git init -b main\n   git add . && git commit -m \"initial commit\"\n   gh repo create gh-EXTENSION-NAME --source=. --public --push\n   ```\n\n7. 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/enterprise-server@3.22/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics).\n\n## Dicas para escrever extensões em linguagem interpretada GitHub CLI\n\n### Manipulando argumentos e sinalizadores\n\nTodos 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.\n\nPor 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.\n\n```bash\n#!/usr/bin/env bash\nset -e\n\nverbose=\"\"\nname_arg=\"\"\nwhile [ $# -gt 0 ]; do\n  case \"$1\" in\n  --verbose)\n    verbose=1\n    ;;\n  --name)\n    name_arg=\"$2\"\n    shift\n    ;;\n  -h|--help)\n    echo \"Add help text here.\"\n    exit 0\n    ;;\n  esac\n  shift\ndone\n\nif [ -z \"$name_arg\" ]\nthen\n  echo \"You haven't told us your name.\"\nelif [ -z \"$verbose\" ]\nthen\n  echo \"Hi $name_arg\"\nelse\n  echo \"Hello and welcome, $name_arg\"\nfi\n```\n\n### Chamar comandos do núcleo em modo não interativo\n\nAlguns GitHub CLI comandos principais solicitarão entrada ao usuário. 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.\n\nPor exemplo, para criar um problema de modo programático, especifique o título e o texto:\n\n```shell\ngh issue create --title \"My Title\" --body \"Issue description\"\n```\n\n### Buscando dados programaticamente\n\nMuitos 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:\n\n```shell\ngh pr list --json number,title,mergeStateStatus\n```\n\nSe 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:\n\n```shell\ngh api user\n```\n\nTodos 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:\n\n```shell\ngh api user --jq '.name'\n```\n\nPara obter mais informações, consulte [`gh help formatting`](https://cli.github.com/manual/gh_help_formatting).\n\n## Criando uma extensão pré-compilada manualmente\n\n1. 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`.\n\n2. No diretório que você criou, adicione um código-fonte. Por exemplo:\n\n   ```golang\n   package main\n   import (\n     \"github.com/cli/go-gh\"\n     \"fmt\"\n   )\n\n   func main() {\n     args := []string{\"api\", \"user\", \"--jq\", `\"You are @\\(.login) (\\(.name))\"` }\n     stdOut, _, err := gh.Exec(args...)\n     if err != nil {\n       fmt.Println(err)\n       return\n     }\n     fmt.Println(stdOut.String())\n   }\n   ```\n\n3. No seu diretório, instale a extensão como uma extensão local.\n\n   ```shell\n   gh extension install .\n   ```\n\n4. Construa o seu código. Por exemplo, com o Go, substituindo `YOUR-USERNAME` pelo nome de usuário GitHub:\n\n   ```shell\n   go mod init github.com/YOUR-USERNAME/gh-whoami\n   go mod tidy\n   go build\n   ```\n\n5. Verifique se sua extensão funciona. Substitua `EXTENSION-NAME` pelo nome da extensão. Por exemplo, `whoami`.\n\n   ```shell\n   gh EXTENSION-NAME\n   ```\n\n6. No seu diretório, crie um repositório para publicar a sua extensão. Substitua `EXTENSION-NAME` pelo nome da extensão.\n\n   > \\[!NOTE]\n   > Tenha cuidado para não fazer confirmação do binário produzido pela etapa de compilação para o controle de versão.\n\n   ```shell\n    git init -b main\n   echo \"gh-EXTENSION-NAME\" >> .gitignore\n   git add main.go go.* .gitignore && git commit -m 'Initial commit'\n   gh repo create \"gh-EXTENSION-NAME\"\n   ```\n\n7. 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].\n\n   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).\n\n   > \\[!NOTE]\n   > 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.\n\n   As liberações podem ser criadas a partir da linha de comando. Por exemplo:\n\n   ```shell\n   git tag v1.0.0\n   git push origin v1.0.0\n   GOOS=windows GOARCH=amd64 go build -o gh-EXTENSION-NAME-windows-amd64.exe\n   GOOS=linux GOARCH=amd64 go build -o gh-EXTENSION-NAME-linux-amd64\n   GOOS=darwin GOARCH=amd64 go build -o gh-EXTENSION-NAME-darwin-amd64\n   gh release create v1.0.0 ./*amd64*\n\n   ```\n\n8. 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 [Classificar repositório com tópicos](/pt/enterprise-server@3.22/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics).\n\n## Tips for writing precompiled GitHub CLI extensions\n\n### Automating releases\n\nConsider 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.\n\n### Using GitHub CLI features from Go-based extensions\n\nConsider using [go-gh](https://github.com/cli/go-gh), a Go library that exposes pieces of `gh` functionality for use in extensions.\n\n## Next steps\n\nTo see more examples of GitHub CLI extensions, look at [repositories with the `gh-extension` topic](https://github.com/topics/gh-extension)."}