Skip to main content

Criando extensões da CLI do 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 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.

Observação: quando você confiar em um script executável, recomendaremos 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

Observação: a execução de 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.

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

    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

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.

  1. 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
    
  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

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.

  1. 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
    
  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.

    Observação: 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.

  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 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 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 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

  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:

    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.

    gh extension install .
    
  4. 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
    
  5. Verifique se sua extensão funciona. Substitua EXTENSION-NAME pelo nome da 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 extensão.

    Observação: 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"
    
  7. 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.

    Observação: para que a 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*
    
    
  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. For more information about how to add a repository topic, see "Classifying your repository with topics."

Tips for writing precompiled GitHub CLI extensions

Automating releases

Consider adding the 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, 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.