Habilidade GitHub CLI (gh)
Use o CLI gh para interagir com repositórios GitHub, issues, pull requests e workflows do GitHub Actions a partir do terminal.
Pré-requisitos
Verifique se o gh está instalado e autenticado:
gh --version
gh auth status
Se não estiver autenticado, execute gh auth login e siga as instruções.
Fluxos de Trabalho Principais
Gerenciamento de Issues
# Listar issues
gh issue list # Issues abertas no repositório atual
gh issue list --state all # Todas as issues, incluindo fechadas
gh issue list --assignee @me # Issues atribuídas a você
gh issue list --label "bug" # Filtrar por label
# Criar issue
gh issue create -t "Título" -b "Descrição"
gh issue create -t "Título" --label "bug,prioridade:alta" --milestone "marco-1"
gh issue create # Modo interativo
# Visualizar/atualizar issue
gh issue view 123 # Visualizar detalhes da issue
gh issue view 123 --web # Abrir no navegador
gh issue edit 123 --add-label "em-andamento"
gh issue close 123
gh issue reopen 123
# Adicionar comentários
gh issue comment 123 -b "Estou trabalhando nisso agora"
Fluxo de Trabalho de Branch e Commit
# Criar branch de funcionalidade/correção
git checkout -b feature/minha-funcionalidade
git checkout -b fix/issue-123
git checkout -b draft/wip-experimento
# Preparar e commitar alterações
git add .
git commit -m "feat: adicionar nova funcionalidade"
git commit -m "fix: resolver issue #123"
# Enviar branch para o remoto
git push -u origin feature/minha-funcionalidade
Gerenciamento de Pull Requests
# Criar PR (vários métodos)
gh pr create # Modo interativo
gh pr create --fill # Preenchimento automático a partir dos commits
gh pr create --draft # Criar como rascunho
gh pr create --draft --fill # Rascunho com preenchimento automático
gh pr create -t "Título" -b "Descrição" -B main
gh pr create --label "revisão-necessária" --assignee @me
# Listar PRs
gh pr list # PRs abertos
gh pr list --assignee @me # Seus PRs
gh pr list --search "review-requested:@me" # PRs solicitando sua revisão
gh pr list --draft # Apenas PRs em rascunho
# Visualizar detalhes do PR
gh pr view 45 # Visualizar PR no terminal
gh pr view 45 --web # Abrir no navegador
Fluxo de Trabalho de Revisão de Código
# Fazer checkout do PR localmente para teste
gh pr checkout 45 # Fazer checkout da branch do PR localmente
# Revisar alterações
gh pr diff 45 # Visualizar diff do PR
gh pr diff # Diff do PR da branch atual
# Adicionar comentários de revisão
gh pr comment 45 -b "LGTM, pequena sugestão na linha 42"
gh pr comment -b "Por favor, adicione testes" # Comentar no PR da branch atual
# Submeter uma revisão formal
gh pr review 45 --approve
gh pr review 45 --request-changes -b "Por favor, corrija o tratamento de erros"
gh pr review 45 --comment -b "Parece bom no geral, algumas sugestões"
# Mesclar
gh pr merge 45 # Mesclagem interativa
gh pr merge 45 --squash # Mesclagem squash
gh pr merge 45 --rebase # Mesclagem rebase
gh pr merge 45 --merge # Commit de mesclagem padrão
gh pr merge 45 --auto # Mesclagem automática quando as verificações passarem
Atualizar PR Existente
gh pr edit 45 --title "Novo título"
gh pr edit 45 --body "Descrição atualizada"
gh pr edit 45 --base develop
gh pr edit 45 --add-label "pronto-para-revisão"
gh pr ready 45 # Marcar como pronto (remover rascunho)
Gerenciamento de Workflows do GitHub Actions
# Listar execuções de workflow
gh run list # Execuções de workflow recentes
gh run list --workflow=ci.yml # Workflow específico
gh run list --status=failure # Apenas execuções com falha
# Visualizar detalhes da execução do workflow
gh run view # Seletor de execução interativo
gh run view 12345 # Execução específica
gh run view 12345 --web # Abrir no navegador
# Acionar workflow
gh workflow run ci.yml # Executar na branch padrão
gh workflow run ci.yml --ref feature/x # Executar em branch específica
gh workflow run ci.yml -f key=value # Com parâmetros de entrada
# Reexecutar tarefas com falha
gh run rerun 12345 # Reexecutar todas as tarefas
gh run rerun 12345 --failed # Reexecutar apenas tarefas com falha
# Visualizar logs de tarefa
gh run view 12345 --log # Saída completa do log
gh run view 12345 --log-failed # Apenas logs de tarefas com falha
# Assistir a uma execução em andamento
gh run watch # Assistir à execução atual
gh run watch 12345 # Assistir a uma execução específica
Referência de Flags Comuns
| Flag | Descrição |
|---|---|
-R, --repo OWNER/REPO | Repositório alvo diferente |
-B, --base | Branch base para PR |
-H, --head | Branch head para PR |
-t, --title | Título para issue/PR |
-b, --body | Corpo/descrição para issue/PR |
-l, --label | Labels (separadas por vírgula) |
-a, --assignee | Nome de usuário do responsável |
-m, --milestone | Nome do marco |
--draft | Criar como PR em rascunho |
--fill | Preencher automaticamente das mensagens de commit |
--web | Abrir no navegador |
-y, --yes | Pular prompts de confirmação |
Variáveis de Ambiente
export GH_TOKEN="ghp_xxxx" # Token de acesso pessoal
export GH_HOST="github.example.com" # Instância do GitHub Enterprise
export GH_REPO="owner/repo" # Repositório padrão
Dicas e Armadilhas
Descrições Multilinha com Markdown
Ao criar issues ou PRs com descrições longas contendo markdown (blocos de código, crases), evite heredocs que podem falhar devido à interpretação do shell. Em vez disso:
# Passo 1: Escrever a descrição em um arquivo temporário (fora do bash)
# Passo 2: Criar a partir do arquivo temporário
gh issue create -t "Título" -b "$(cat descricao_temporaria.txt)"
# Passo 3: Limpar
rm descricao_temporaria.txt
Isso evita problemas com:
- Crases em blocos de código conflitando com substituição de comando
- Caracteres especiais sendo interpretados pelo shell
- Conflitos de delimitador de heredoc
Usando Descrição de Arquivos Existentes
Para criar uma issue ou PR a partir de um arquivo de plano markdown:
# Use a flag body-file para descrições limpas baseadas em arquivo
gh issue create -t "Título" --body-file docs/planos/meu-plano.md
gh pr create -t "Título" --body-file docs/planos/meu-plano.md
Referência Detalhada
Para opções de comando abrangentes e exemplos, consulte references/commands.md.