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 obter mais informações sobre como usar as extensões de GitHub CLI, consulte "Usando extensões de GitHub CLI".

É necessário um repositório para cada extensão que você criar. O nome do repositório deve iniciar 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.

Criando uma extensão interpretada com gh extension create

Você pode usar o comando gh extension create para criar um projeto para sua extensão, incluindo um script de bash que contém um código inicial.

1. Configure uma nova extensão usando a o subcomando gh extension create. Substitua EXTENSION-NAME pelo nome da sua extensão.

   gh extension create EXTENSION-NAME

2. Siga as instruções impressas para finalizar e, opcionalmente, publicar sua extensão.

A criação de uma extensão pré-compilada em Go com gh extension create

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

1. Configure uma nova extensão usando a o subcomando gh extension create. Substitua EXTENSION-NOME pelo nome da sua extensão e especifique --precompiled=go.

   gh extension create --precompiled=go EXTENSION-NAME

2. Siga as instruções impressas para finalizar e, opcionalmente, publicar sua extensão.

Criando 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 fora do G8, incluindo o scaffolding do fluxo de trabalho.

1. Configure uma nova extensão usando a o subcomando gh extension create. Substitua EXTENSION-NOME pelo nome da sua extensão e especifique --precompiled=other.

   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 código para criar sua extensão e garantir que a sua extensão possa ser construída 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 denominado gh-EXTENSION-NAME para a sua extensão. Substitua EXTENSION-NAME pelo nome da sua 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.

   Observação: Certifique-se de que seu arquivo seja 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, em seguida, git update-index --chmod=+x file_name.

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

   #!/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.

   gh extension install .

5. Verifique se sua extensão funciona. Substitua EXTENSION-NAME pelo nome da sua extensão. Por exemplo, whoami.

   gh EXTENSION-NAME

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

   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 do tópico de

gh-extension. Para obter mais informações sobre como adicionar um tópico do repositório, consulte "Classificando seu 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 gh my-extension-name serão passados para o script da extensão. Em um script de bash, você pode fazer referência a argumentos com $1, $2, etc. Você pode usar argumentos para inserir o 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 flag, o script imprime texto ao invés de continuar a execução. Quando o script é chamado com o o sinalizador --name, o script define o próximo valor após o sinalizador para name_arg. Quando o script é chamado com o sinalizador --verbose, o script imprime uma saudação 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

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 principais são compatíveis o sinalizador --json para obter dados programaticamente. 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 do núcleo 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, consulte gh help formatting.

Criando uma extensão pré-compilada manualmente

1. Crie um diretório local denominado gh-EXTENSION-NAME para a sua extensão. Substitua EXTENSION-NAME pelo nome da sua extensão. Por exemplo, gh-whoami.

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

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

1. No seu diretório, instale a extensão como uma extensão local.

<pre><code class="hljs language-shell">gh extension install .</code></pre>

1. Construa o seu código. Por exemplo, com o Go, substituindo YOUR-USERNAME pelo seu nome de usuário do GitHub:

<pre><code class="hljs language-shell">go mod init github.com/<em>YOUR-USERNAME</em>/gh-whoami
go mod tidy
go build</code></pre>

1. Verifique se sua extensão funciona. Substitua EXTENSION-NAME pelo nome da sua extensão. Por exemplo, whoami.

<pre><code class="hljs language-shell">gh <em>EXTENSION-NAME</em></code></pre>

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

   Observação: Tenha cuidado para não fazer commit do binário produzido pela etapa de compilação para o controle de versão.

<pre><code class="hljs language-shell">git init -b main
echo "gh-<em>EXTENSION-NAME</em>" >> .gitignore
git add main.go go.* .gitignore && git commit -m'Initial commit'
gh repo create "gh-<em>EXTENSION-NAME</em>"</code></pre>

1. 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 devem seguir uma convenção de nomes e ter um sufixo de OS-ARCHITECTURE[EXTENSION].

   Por exemplo, uma extensão denominada whoami compilada para Windows 64bit teria o nome gh-whoami-windows-amd64.exe enquanto a mesma extensão compilada para Linux 32bit teria o nome gh-whoami-linux-386. Para ver uma lista taxativa de combinações de OS e de arquitetura reconhecidas por seg, consulte este código-fonte.

   Observação: Para que a sua extensão seja executada corretamente no Windows, seu arquivo de ativo deve 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:

2. 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 do tópico de gh-extension. Para obter mais informações sobre como adicionar um tópico do repositório, consulte "Classificando seu repositório com tópicos".

Dicas para escrever extensões de GitHub CLI pré-compiladas

Automatizando as versões

Considere adicionar a ação gh-extension-precompilar ao fluxo de trabalho no seu projeto. Esta ação irá produzir automaticamente binários com compilação cruzada do Go para a sua extensão e irá fornecer uma estrutura de criação para extensões pré-compiladas que não são para o Go.

Usando funcionalidades de GitHub CLI a partir de extensões do Go

Considere usar go-gh, uma biblioteca do Go que expõe a funcionalidade gh para uso em extensões.

Próximas etapas

Para ver mais exemplos de extensões GitHub CLI, consulte repositórios com o tópico de extensão gh-extension.