GitHub CLI

A CLI gh gerencia pull requests, issues, execuções de Actions e releases a partir do terminal - combinando com a forma como as equipes Python já criam scripts para uv e pytest em CI.

Receita

gh auth login
gh pr create --fill --base main
gh pr checks --watch
gh pr merge --squash --delete-branch

Quando usar isso:

Abrir PRs sem sair do terminal
Assistir ao workflow ruff/pytest em um push
Rotulagem em massa de issues ou upload de assets de release
Scriptar a higiene do repositório em runbooks da equipe de plataforma

Exemplo de Trabalho

# Após o trabalho na feature
git push -u origin feat/bill-42-tax
 
gh pr create \
  --title "feat(billing): add tax line item [BILL-42]" \
  --body "Adds VAT calculation; updates uv.lock for pydantic bump." \
  --reviewer @acme/billing-team
 
# Assistir à CI (mesmas etapas que .github/workflows/pr.yml)
gh pr checks 42 --watch
 
# Solicitações de alterações abordadas - mesclar quando estiver verde
gh pr merge 42 --squash --delete-branch

O que isso demonstra:

--fill usa mensagens de commit para o corpo do rascunho quando apropriado
--watch bloqueia até que as verificações necessárias sejam concluídas
Política de merge squash alinhada com o documento de branching
Exclusão automática de branch mantém o remoto organizado

Mergulho Profundo

Como Funciona

gh auth - Armazena token ou usa SSH para operações git.
gh pr - Empacota as APIs REST/GraphQL de GitHub Pull Requests.
gh run - Lista e visualiza execuções de workflow de Actions.
gh api - API bruta autenticada para scripts personalizados.

Comandos de Alto Valor

Tarefa	Comando
Fazer checkout de PR localmente	`gh pr checkout 42`
Visualizar diff de PR	`gh pr diff 42`
Reexecutar job falho	`gh run rerun <run-id> --failed`
Criar release	`gh release create v1.2.0 dist/*`
Listar issues	`gh issue list --label bug`

Notas de Python

# Comentar snippet de falha do pytest no PR
gh pr comment 42 --body "$(uv run pytest -q 2>&1 | tail -20)"

Armadilhas

Escopo do token de autenticação - repo e workflow necessários para Actions privadas. Correção: gh auth refresh -s repo,workflow.
Repositório padrão errado - gh tem como alvo o cwd remoto. Correção: gh repo set-default acme/billing-api.
Merge antes da CI verde - Ignora a política se for administrador. Correção: aguarde gh pr checks.
Template de PR ignorado - Corpos vazios atrasam a revisão. Correção: .github/pull_request_template.md + gh pr create --template.
Vazamento de segredos em comentários - Logs colados podem incluir tokens. Correção: redigir antes de gh pr comment.
Discrepância entre squash e merge - A política da organização pode proibir squash. Correção: gh pr merge --merge de acordo com ADR.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Interface web do GitHub	Revisão visual de imagens/UI	Criação repetitiva de PR
`hub` (legado)	Scripts antigos	Automação nova - usar `gh`
`glab` do GitLab	Hospedagem GitLab	Organização GitHub
API + curl	Endpoints exóticos	`gh api` já encapsula autenticação

FAQs

SSH ou HTTPS para gh auth?

SSH se o git já usa chaves SSH; HTTPS com token para controle de PAT granular.

gh em CI?

Use o segredo GH_TOKEN com o mínimo de escopo - não PAT pessoal em runners compartilhados.

Draft PR da CLI?

gh pr create --draft para feedback inicial antes da fila de revisão.

Aprovar PR como revisor?

gh pr review 42 --approve quando a política permitir revisões via CLI.

Disparar workflow_dispatch?

gh workflow run pr.yml --ref feat/branch

Baixar artefatos de Actions?

gh run download <run-id> -n coverage-report

Múltiplos remotos?

gh pr create --repo acme/other-service tem como alvo um repositório explícito.

Issue a partir de CI falha?

gh issue create --title "CI flaky test_tax" --body "run id ..."

Alias de fluxos comuns?

gh alias set prc 'pr create --fill --web' - a equipe compartilha a documentação de aliases.

Enterprise Server?

gh auth login --hostname github.acme.com para GHES.

Relacionados

Comandos Essenciais de Git - git push antes do PR
Pipelines de CI/CD - paridade de workflow
Branching & Merging - políticas de merge
Melhores Práticas de Git - normas de git da equipe

Versões da Pilha: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.

GitHub CLI

A CLI gh gerencia pull requests, issues, execuções de Actions e releases a partir do terminal - combinando com a forma como as equipes Python já criam scripts para uv e pytest em CI.

Receita

gh auth login
gh pr create --fill --base main
gh pr checks --watch
gh pr merge --squash --delete-branch

Quando usar isso:

Abrir PRs sem sair do terminal
Assistir ao workflow ruff/pytest em um push
Rotulagem em massa de issues ou upload de assets de release
Scriptar a higiene do repositório em runbooks da equipe de plataforma

Exemplo de Trabalho

# Após o trabalho na feature
git push -u origin feat/bill-42-tax
 
gh pr create \
  --title "feat(billing): add tax line item [BILL-42]" \
  --body "Adds VAT calculation; updates uv.lock for pydantic bump." \
  --reviewer @acme/billing-team
 
# Assistir à CI (mesmas etapas que .github/workflows/pr.yml)
gh pr checks 42 --watch
 
# Solicitações de alterações abordadas - mesclar quando estiver verde
gh pr merge 42 --squash --delete-branch

O que isso demonstra:

--fill usa mensagens de commit para o corpo do rascunho quando apropriado
--watch bloqueia até que as verificações necessárias sejam concluídas
Política de merge squash alinhada com o documento de branching
Exclusão automática de branch mantém o remoto organizado

Mergulho Profundo

Como Funciona

gh auth - Armazena token ou usa SSH para operações git.
gh pr - Empacota as APIs REST/GraphQL de GitHub Pull Requests.
gh run - Lista e visualiza execuções de workflow de Actions.
gh api - API bruta autenticada para scripts personalizados.

Comandos de Alto Valor

Tarefa	Comando
Fazer checkout de PR localmente	`gh pr checkout 42`
Visualizar diff de PR	`gh pr diff 42`
Reexecutar job falho	`gh run rerun <run-id> --failed`
Criar release	`gh release create v1.2.0 dist/*`
Listar issues	`gh issue list --label bug`

Notas de Python

# Comentar snippet de falha do pytest no PR
gh pr comment 42 --body "$(uv run pytest -q 2>&1 | tail -20)"

Armadilhas

Escopo do token de autenticação - repo e workflow necessários para Actions privadas. Correção: gh auth refresh -s repo,workflow.
Repositório padrão errado - gh tem como alvo o cwd remoto. Correção: gh repo set-default acme/billing-api.
Merge antes da CI verde - Ignora a política se for administrador. Correção: aguarde gh pr checks.
Template de PR ignorado - Corpos vazios atrasam a revisão. Correção: .github/pull_request_template.md + gh pr create --template.
Vazamento de segredos em comentários - Logs colados podem incluir tokens. Correção: redigir antes de gh pr comment.
Discrepância entre squash e merge - A política da organização pode proibir squash. Correção: gh pr merge --merge de acordo com ADR.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Interface web do GitHub	Revisão visual de imagens/UI	Criação repetitiva de PR
`hub` (legado)	Scripts antigos	Automação nova - usar `gh`
`glab` do GitLab	Hospedagem GitLab	Organização GitHub
API + curl	Endpoints exóticos	`gh api` já encapsula autenticação

FAQs

SSH ou HTTPS para gh auth?

SSH se o git já usa chaves SSH; HTTPS com token para controle de PAT granular.

gh em CI?

Use o segredo GH_TOKEN com o mínimo de escopo - não PAT pessoal em runners compartilhados.

Draft PR da CLI?

gh pr create --draft para feedback inicial antes da fila de revisão.

Aprovar PR como revisor?

gh pr review 42 --approve quando a política permitir revisões via CLI.

Disparar workflow_dispatch?

gh workflow run pr.yml --ref feat/branch

Baixar artefatos de Actions?

gh run download <run-id> -n coverage-report

Múltiplos remotos?

gh pr create --repo acme/other-service tem como alvo um repositório explícito.

Issue a partir de CI falha?

gh issue create --title "CI flaky test_tax" --body "run id ..."

Alias de fluxos comuns?

gh alias set prc 'pr create --fill --web' - a equipe compartilha a documentação de aliases.

Enterprise Server?

gh auth login --hostname github.acme.com para GHES.

Relacionados

Comandos Essenciais de Git - git push antes do PR
Pipelines de CI/CD - paridade de workflow
Branching & Merging - políticas de merge
Melhores Práticas de Git - normas de git da equipe

Versões da Pilha: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.

GitHub CLI

Buscar na documentação

GitHub CLI