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.
-
Configure uma nova extensão usando o subcomando
gh extension create
. SubstituaEXTENSION-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
. SubstituaEXTENSION-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
. SubstituaEXTENSION-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. SubstituaEXTENSION-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.
Observação: verifique se o arquivo é executável. No UNIX, você pode executar
chmod +x file_name
na linha de comando para tornarfile_name
executável. No Windows, executegit init -b main
,git add file_name
egit 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ópicogh-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. SubstituaEXTENSION-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.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"
-
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 nomegh-whoami-windows-amd64.exe
, enquanto a mesma extensão compilada para o Linux de 32 bits terá o nomegh-whoami-linux-386
. Para ver uma lista abrangente de combinações de sistema operacional e arquitetura reconhecidas porgh
, 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*
-
Optionally, to help other users discover your extension, add the repository topic
gh-extension
. This will make the extension appear on thegh-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.