Criando extensões da CLI do GitHub

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 saber mais sobre como usar extensões do GitHub CLI, confira Usando as extensões de CLI do GitHub.

É necessário um repositório para cada extensão que você criar. O nome do repositório precisa começar com gh-. O 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.

Use o comando gh extension create para criar um projeto para sua extensão, incluindo um script do Bash que contém um código inicial.

Configure uma nova extensão usando o subcomando gh extension create. Substitua EXTENSION-NAME pelo nome da extensão.
```
gh extension create EXTENSION-NAME
```
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`

Use o argumento --precompiled=go para criar um projeto baseado em Go para sua extensão, incluindo o scaffolding do Go, o scaffolding do fluxo de trabalho e o código inicial.

Configure uma nova extensão usando o subcomando gh extension create. Substitua EXTENSION-NAME pelo nome da extensão e especifique --precompiled=go.
```
gh extension create --precompiled=go EXTENSION-NAME
```
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`

Use o argumento --precompiled=other para criar um projeto para sua extensão pré-compilada que não é do Go, incluindo o scaffolding do fluxo de trabalho.

Configure uma nova extensão usando o subcomando gh extension create. Substitua EXTENSION-NAME pelo nome da extensão e especifique --precompiled=other.
```
gh extension create --precompiled=other EXTENSION-NAME
```
Adicione um código inicial para sua extensão na linguagem compilada escolhida.
Preencha script/build.sh com o código para compilar a extensão e verificar se ela pode ser compilada automaticamente.
Siga as instruções impressas para finalizar e, opcionalmente, publicar sua extensão.

Criando uma extensão interpretada manualmente

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.
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, executegit init -b main, git add file_name e git update-index --chmod=+x file_name.

Escreva seu script no arquivo executável. Por exemplo:

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

No seu diretório, instale a extensão como uma extensão local.
```
gh extension install .
```
Verifique se sua extensão funciona. Substitua EXTENSION-NAME pelo nome da extensão. Por exemplo, whoami.
```
gh EXTENSION-NAME
```

No seu diretório, crie um repositório para publicar a sua extensão. Substitua EXTENSION-NAME pelo nome da extensão.

git init -b main
git add . && git commit -m "initial commit"
gh repo create gh-EXTENSION-NAME --source=. --public --push

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 seja exibida na página do tópico gh-extension. Para saber mais sobre como adicionar um tópico de repositório, confira Classificar repositório com tópicos.

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.

#!/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 principais pedirão entrada ao usuário. Ao escrever com esses comandos, a instrução é frequentemente 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:

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:

gh pr list --json number,title,mergeStateStatus

Se não houver um comando básico para buscar dados específicos do GitHub, você poderá usar o comando gh api para acessar a API do GitHub. Por exemplo, para obter informações sobre o usuário atual:

gh api user

Todos os comandos que os dados JSON de saída também têm opções para filtrar esses dados em algo mais imediatamente utilizável por scripts. Por exemplo, para obter o nome do usuário atual:

gh api user --jq '.name'

Para obter mais informações, confira gh help formatting.

Criando uma extensão pré-compilada manualmente

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.

No diretório que você criou, adicione um código-fonte. Por exemplo:

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())
}

No seu diretório, instale a extensão como uma extensão local.
```
gh extension install .
```
Construa o seu código. Por exemplo, com o Go, substituindo YOUR-USERNAME pelo seu nome de usuário do GitHub:
```
go mod init github.com/YOUR-USERNAME/gh-whoami
go mod tidy
go build
```
Verifique se sua extensão funciona. Substitua EXTENSION-NAME pelo nome da extensão. Por exemplo, whoami.
```
gh EXTENSION-NAME
```
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 commit do binário produzido pela etapa de build para o controle de versão.
```
 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"
```
Crie uma versão para 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 abrangente de combinações de sistema operacional e arquitetura reconhecidas por gh, confira este código-fonte.

Note

Para que sua extensão seja executada corretamente no Windows, o arquivo de ativo precisa ter uma extensão .exe. Não é necessária qualquer extensão para outros sistemas operacionais.

As versões podem ser criadas a partir da linha de comando. Por exemplo:
```
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 the gh-extension topic page. For more information about how to add a repository topic, see Classifying your repository with topics.

Criando extensões da CLI do GitHub

Neste artigo