Ir para o conteúdo
Promovaweb

GitHub CLI: o gh no terminal

O GitHub CLI é a ferramenta de linha de comando de código aberto do GitHub, chamada pelo comando gh, que leva pull requests, issues, workflows do Actions e releases para o terminal. Ele conversa com a API do GitHub usando o token da sua autenticação, por isso o mesmo comando que você digita funciona dentro de um script, de um agente ou de um job do Actions.

Ficha e sumário da página

Referência técnica
GitHub CLI v2.104.0
Revisão
13 de novembro de 2026
Conteúdo
Documentação oficial consultada
  1. Uma ferramenta para o GitHub, separada do Git
  2. Os grupos de comandos
  3. Autenticação e escolha do repositório
  4. O gh em scripts e agentes

Uma ferramenta para o GitHub, separada do Git

O Git cuida do histórico local, dos commits às branches enviadas com push. O GitHub CLI cuida do que existe só na plataforma, como o pull request e a release. Pela documentação oficial, o gh leva para o terminal os pull requests e as issues, junto com o GitHub Actions e outros recursos da plataforma. Os dois convivem no mesmo fluxo: o git push envia a branch e o gh pr create abre a proposta de merge a partir dela.

O projeto é aberto, com código no repositório cli/cli sob licença MIT. Ele roda no macOS, no Windows e no Linux, com instalação pelo Homebrew, pelo WinGet, pelos pacotes oficiais para Debian, Ubuntu e as distribuições baseadas em RPM ou por binários pré-compilados de cada release. O gh funciona com o GitHub.com, com o GitHub Enterprise Cloud e com as versões suportadas do GitHub Enterprise Server. Nos runners hospedados do GitHub Actions, a ferramenta já vem instalada.

A versão de referência deste portal é a v2.104.0, publicada em 12 de novembro de 2026. Ela trouxe uma confirmação extra no gh repo delete para repositórios privados ou internos com forks. Na mesma versão, o gh auth status mostra no terminal o erro original quando a falha vem do limite de requisições, do servidor ou da rede.

Os grupos de comandos

O gh agrupa os comandos por recurso do GitHub. Cada grupo tem subcomandos para criar, listar, ver e alterar aquele recurso. A grade abaixo reúne os grupos que aparecem no caminho do commit à release, com os nomes do manual da v2.104.0:

  • gh repoClona, cria, mostra e apaga repositórios.
  • gh prAbre, revisa, confere as checagens e faz o merge de pull requests.
  • gh issueAbre, lista, comenta e fecha issues.
  • gh runLista e acompanha as execuções dos workflows do Actions.
  • gh releaseCria, lista, mostra e baixa releases.
  • gh apiChama qualquer endpoint da API do GitHub com a sua autenticação.

O manual lista outros grupos, como gh secret e gh variable para os valores do Actions, gh workflow para disparar workflows manuais, gh ruleset para os rulesets das branches e gh extension para os comandos criados pela comunidade. O gh api cobre o que nenhum grupo cobre: ele faz a requisição autenticada para qualquer endpoint da API REST ou GraphQL e devolve o JSON, que um script lê para consultar o que a interface não mostra.

Autenticação e escolha do repositório

O gh auth login autentica o terminal no GitHub e guarda o token para os próximos comandos. Em scripts e jobs, o token chega por variável de ambiente: o GH_TOKEN tem prioridade sobre as credenciais guardadas, com o GITHUB_TOKEN aceito como segunda opção. Num job do Actions, a documentação orienta definir GH_TOKEN com o valor de secrets.GITHUB_TOKEN em cada passo que chama o gh, o que entrega ao comando o token criado para aquele job. O repositório vem da pasta atual: dentro de um clone, o gh lê o remoto e sabe em qual repositório agir.

As variáveis de ambiente mudam esse comportamento sem alterar o comando. O arquivo abaixo reúne as que mais aparecem em scripts e agentes, separadas pelo que cada uma controla. A lista completa, com as 34 variáveis da v2.104.0, está na página de variáveis de ambiente do GitHub CLI:

.env do script

Autenticação e alvo

GH_TOKEN=
Token de acesso usado no lugar da autenticação guardada pelo gh auth login.
GH_HOST=
O host do GitHub, como um Enterprise Server, quando o comando não informa e a pasta atual não indica qual é.
GH_REPO=
O repositório alvo no formato [HOST/]DONO/REPO, para comandos que agiriam no repositório da pasta atual.

Execução sem interação

GH_PROMPT_DISABLED=
Desliga as perguntas interativas, para o script não parar esperando resposta.
GH_PAGER=
O programa de paginação que recebe a saída padrão, como o less.
NO_COLOR=
Com qualquer valor, tira as cores da saída, útil em logs de CI e em arquivos.
Variáveis de ambiente do GitHub CLI na v2.104.0 que mudam a execução de um script sem alterar o comando. O token fica fora do arquivo versionado: ele chega pelo ambiente do job ou pelo gerenciador de secrets.

O gh em scripts e agentes

O comando que você digita à mão também roda numa automação. A opção --json de comandos como gh pr list e gh release view devolve campos escolhidos em JSON. A opção --jq filtra esse JSON na própria chamada. Um script de release, por exemplo, confere se a tag já tem release com gh release view e só cria uma nova quando a consulta falha.

Os agentes de código usam o gh pelo mesmo caminho. O repositório cli/cli descreve uma skill de agente para conduzir o gh a partir de agentes de código, instalada com gh skill install. A nota da v2.104.0 cita esses agentes de forma direta: um workflow sem interação ou um agente que apaga um repositório privado com forks precisa declarar a opção --accept-cascading-deletion-of-private-forks, mesmo com --yes, porque os forks privados somem junto.

As releases do próprio gh aparecem no changelog do GitHub CLI, com um artigo em português para cada versão. O próximo assunto é o que o GitHub vigia no repositório sem você chamar nenhum comando: os alertas de dependências, os segredos expostos e os avisos de segurança, na página Segurança do repositório.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.