Criando um Pull Request de uma Sessão de Código Claude com gh
Uma vez que o Claude Code fez um conjunto de alterações em uma sessão de trabalho, ele pode fazer o commit delas e abrir um pull request no GitHub sem sair dessa sessão, usando o gh CLI.
Resumo
Abrir um PR de uma sessão significa que o Claude Code executa os mesmos comandos git e gh que um desenvolvedor digitaria manualmente.
Não existe um "recurso de PR do Claude Code" separado - o gh CLI é a própria ferramenta oficial de linha de comando do GitHub, e o Claude Code simplesmente a invoca.
Isso significa que tudo o que você poderia fazer com gh pr create sozinho, o Claude Code pode fazer como parte da finalização de uma tarefa que você solicitou.
Também significa que o PR resultante parece completamente normal para sua equipe - mesmo formato de título, mesmo corpo, mesmas verificações sendo executadas nele.
O único pré-requisito é que o gh esteja instalado e autenticado no ambiente em que a sessão está sendo executada.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
git add -A
git commit -m "Add rate limiting to the search endpoint"
git push -u origin HEAD
gh pr create --title "Add rate limiting to the search endpoint" \
--body "Adds a sliding-window rate limiter to the search endpoint. Fixes #482."Quando usar isso:
- Você pediu ao Claude Code para implementar um recurso ou correção, e a alteração está pronta para revisão.
- Você deseja que o título e o corpo do PR sejam escritos na mesma sessão em que a alteração foi feita, para que a descrição corresponda ao diff real.
- Você está trabalhando em um branch de recurso e deseja pular a troca para um navegador para abrir o PR.
- Você deseja um padrão repetível que também possa ser inserido em um script ou etapa de CI posteriormente.
Exemplo de Trabalho
#!/usr/bin/env bash
set -euo pipefail
# 1. Confirm there is something to commit.
git status --short
# 2. Stage and commit the change.
git add -A
git commit -m "Add rate limiting to the search endpoint
Adds a token-bucket limiter in middleware/rate-limit.py, applied to
the /api/search route. Limit is 60 requests/minute per API key."
# 3. Push the current branch, creating it on the remote if needed.
git push -u origin HEAD
# 4. Open the PR against the repository's default base branch.
gh pr create \
--title "Add rate limiting to the search endpoint" \
--body "$(cat <<'EOF'
## Summary
- Adds a token-bucket rate limiter to /api/search
- Limit: 60 requests/minute per API key
- Returns HTTP 429 with a Retry-After header when exceeded
## Test plan
- [x] Unit tests for the limiter's window boundaries
- [x] Manual test: exceeded the limit locally and confirmed 429 response
Fixes #482
EOF
)"
# 5. Print the new PR's URL for confirmation.
gh pr view --web=false --json url --jq .urlO que isso demonstra:
- Usando um heredoc (
$(cat <<'EOF' ... EOF)) para passar um corpo de PR de múltiplos parágrafos sem problemas de escape. - Enviando com
-upara que o branch seja rastreado no remoto antes quegh pr createseja executado. - Estruturando o corpo do PR com um Resumo e Plano de teste, o que corresponde ao que a maioria das equipes orientadas a revisão espera.
- Confirmando o resultado com
gh pr view --json urlem vez de assumir que o comando foi bem-sucedido. - Referenciando um número de issue (
Fixes #482) para que o GitHub vincule e feche automaticamente a issue na mesclagem.
Mergulho Profundo
Como Funciona
gh pr createlê as informações de rastreamento do branch atual para determinar contra o que enviar, e o branch padrão do repositório (geralmentemain) como base do PR, a menos que--baseseja passado explicitamente.- O comando requer que o branch já exista no remoto -
git push -u origin HEADcuida disso em uma única etapa, enviando e configurando o rastreamento. --titlee--bodysão opcionais; omiti-los faz com queghentre em um prompt interativo, que é por que o uso orientado a sessão quase sempre os fornece explicitamente.- Uma vez criado,
gh pr createimprime a URL do novo PR na saída padrão, o que é útil para uma sessão relatar de volta para você. - Por baixo dos panos,
ghse autentica usando o token armazenado porgh auth login, a mesma credencial usada para todos os outros subcomandosgh.
Flags em Resumo
| Flag | Propósito |
|---|---|
--title | Define o título do PR diretamente, pulando o prompt interativo. |
--body | Define a descrição do PR; suporta texto multilinha via heredoc ou --body-file. |
--base | Substitui o branch base padrão (ex: --base develop). |
--draft | Abre o PR como um rascunho, útil para trabalho ainda em andamento. |
--reviewer | Solicita um revisor ou equipe específica por nome de usuário/handle. |
--fill | Preenche automaticamente o título e o corpo do histórico de commits do branch em vez de especificá-los. |
Notas do Bash
# --fill saves typing when the branch has one clean commit whose message
# already reads like a good PR title and body.
git add -A
git commit -m "Add rate limiting to the search endpoint"
git push -u origin HEAD
gh pr create --fillArmadilhas
- Esquecer de enviar antes de
gh pr create.gh pr createprecisa que o branch exista no remoto primeiro; se você pulargit push -u origin HEAD, o comando falhará pedindo para você enviar. Correção: sempre envie com-uimediatamente antes de criar o PR, ou deixe o prompt do--fillenviá-lo para você. - Fazer commit diretamente no branch padrão. Abrir um PR de
maincontramainnão faz sentido -gh pr createirá gerar um erro ou se comportar de forma inesperada. Correção: crie e faça checkout de um branch de recurso (git checkout -b <nome-do-branch>) antes de fazer as alterações. - Um token de autenticação
ghexpirado ou ausente. Comandos falham silenciosamente com um erro de autenticação segh auth loginnunca foi executado ou o token expirou. Correção: executegh auth statusprimeiro; reautentique comgh auth loginse ele relatar que não está logado. - Um corpo de PR com caracteres especiais não escapados. Passar
--bodycomo uma string entre aspas simples pode falhar em aspas ou backticks embutidos. Correção: use um heredoc (como no Exemplo de Trabalho) ou escreva o corpo em um arquivo e passe--body-file. - Assumir que
gh pr createabre contra o branch que você pretendia. Se você não estiver no branch que pensa que está, o PR acabará com o diff errado. Correção: executegit statusougit branch --show-currentimediatamente antes de criar o PR para confirmar. - Abrir um PR sem uma issue vinculada quando sua equipe exige uma. Alguns processos de revisão esperam que cada PR referencie uma issue de rastreamento. Correção: inclua
Fixes #<número>ouRefs #<número>no corpo, e confirme o número da issue antes de executar o comando.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| Abrir o PR manualmente na interface web do GitHub | Você quer revisar o diff visualmente antes de escrever a descrição | Você já está em uma sessão do Claude Code e quer evitar trocar de contexto |
gh pr create --fill | O branch tem um único commit limpo e bem escrito | A alteração abrange vários commits e precisa de um resumo escrito à mão |
| Um workflow do GitHub Actions que abre PRs em um agendamento (ex: atualizações de dependência) | O PR é totalmente automatizado e não precisa de julgamento orientado a sessão | O corpo do PR precisa descrever o raciocínio específico do trabalho desta sessão |
git push mais uma etapa de CI separada que abre o PR | O pipeline da sua equipe já possui a criação de PR como política | Você quer que o PR seja aberto imediatamente, na mesma etapa do commit |
FAQs
Preciso dizer ao Claude Code o comando gh exato a ser executado?
Não - você pode pedir em linguagem natural ("faça commit disso e abra um PR"), e o Claude Code executa os comandos git e gh equivalentes por conta própria; conhecer os comandos subjacentes apenas ajuda você a entender e verificar o que ele fez.
Qual branch base o gh pr create tem como alvo por padrão?
O branch padrão configurado do repositório, geralmente main ou master, a menos que você passe --base para direcionar outra coisa.
Posso abrir um PR de rascunho em vez de um pronto para revisão?
Sim, adicione --draft a gh pr create; PRs de rascunho não solicitam revisões automaticamente e sinalizam que o trabalho ainda está em andamento.
O que acontece se o branch já tiver um PR aberto?
gh pr create informará que um PR já existe para esse branch e não criará um duplicado; use gh pr view para ver o existente em vez disso.
O gh pr create executa alguma verificação de CI automaticamente?
Abrir o PR aciona quaisquer workflows do GitHub Actions que estejam configurados para serem executados em eventos pull_request no repositório - o gh em si não executa verificações diretamente.
Posso especificar revisores ao criar o PR?
Sim, com --reviewer <nome-de-usuario> (ou um handle de equipe); você pode passá-lo várias vezes para mais de um revisor.
Existe uma maneira de pré-visualizar o PR antes que ele seja realmente criado?
gh pr create tem um modo interativo que mostra uma pré-visualização e pede confirmação quando você omite --title/--body; o uso scriptado pula essa pré-visualização fornecendo ambas as flags diretamente.
E se minha mensagem de commit for longa e multilinha?
Use um heredoc para o argumento da flag -m, a mesma técnica mostrada para --body no Exemplo de Trabalho, para que as novas linhas sejam preservadas corretamente.
O título do PR precisa corresponder à mensagem de commit?
Não, eles são independentes - --title define o título do PR explicitamente, independentemente do que as mensagens de commit dizem, a menos que você use --fill, que deriva ambos do histórico de commits.
O Claude Code pode abrir um PR contra um fork em vez do repositório de origem?
Sim, gh pr create suporta --repo para direcionar um repositório específico, que é como um PR é aberto de um fork de volta para o projeto upstream.
Como confirmo que o PR foi realmente criado com sucesso?
Verifique a URL impressa pelo comando, ou execute gh pr view imediatamente depois, que imprime os detalhes do PR associado ao branch atual, se houver um.
Qual é o mínimo que preciso ter instalado para que isso funcione?
Apenas o gh CLI, autenticado uma vez via gh auth login, e um repositório git com um remote do GitHub configurado - nenhuma configuração adicional do Claude Code é necessária.
Relacionados
- Noções Básicas de Integração com GitHub - instalando e autenticando o
ghCLI antes de usá-lo em uma sessão. - Como o Claude Code se Encaixa no Seu Fluxo de Trabalho de Pull Request do GitHub - onde a abertura de um PR se situa em relação à revisão e resposta ao feedback.
- Respondendo Automaticamente a Comentários de Revisão de PR - o próximo passo natural assim que este PR receber feedback.
- Melhores Práticas de Integração com GitHub - padrões para manter PRs abertos por sessão seguros e revisáveis.
Versões do Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5. Nomes de modelos, preços e recursos de produtos mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.