Pull request no Git: o que é e como criar um PR no GitHub

Um pull request (PR) é uma proposta para integrar as alterações de uma branch em outra, publicada em uma plataforma como o GitHub. Você envia a branch ao servidor, abre o PR, a equipe vê o diff, comenta linhas, executa as verificações automáticas e só depois clica no botão de mesclar. No GitLab, o mesmo mecanismo se chama merge request (MR). Se a pergunta é «o que é git pull request?», a resposta curta é: o ponto de controle entre «escrevi o código» e «o código chega à main».

O que significa pull request e de onde vem o nome

O nome surgiu por tradição. O autor das alterações pede ao responsável pelo repositório que «puxe» (pull) a sua branch, daí pull request. O GitLab preferiu chamar pelo resultado: merge request, pedido de mesclagem. Bitbucket e Azure DevOps usam «pull request». Na essência é a mesma coisa: uma branch de origem, uma branch de destino, uma descrição, a discussão, as verificações e o botão de mesclar.

É importante entender que o pull request não faz parte do Git. No Git não existe um objeto «PR»; ele não pode ser criado com um commit nem encontrado na pasta .git. É uma entidade da plataforma: o GitHub guarda a descrição, os comentários e o status das verificações, enquanto o Git cuida apenas das branches e dos commits que fazem parte do PR.

Na conversa entre desenvolvedores, PR quase sempre significa pull request: «manda o PR», «PR para revisão», «mesclei o PR». Para o GitLab se diz MR.

Pull request e git pull: qual é a diferença

Essas duas coisas são confundidas o tempo todo por causa das palavras parecidas. O comando git pull baixa os commits novos do repositório remoto e os integra imediatamente à sua branch atual: é uma operação local, no terminal. O pull request é uma página do GitHub com a proposta de mesclar uma branch em outra.

Não existe um comando «git pull request» no Git. Há um utilitário antigo, git request-pull, mas ele apenas gera o texto de um e-mail com o resumo das alterações para ser enviado por lista de discussão; não tem relação com os PRs do GitHub.

Para que servem os pull requests

Enquanto um projeto é tocado por uma pessoa só, é possível fazer commit direto na main. Assim que há duas ou mais pessoas, os push diretos para a branch principal viram fonte de builds quebrados e de trabalho perdido. O pull request resolve vários problemas ao mesmo tempo:

• revisão de código: outra pessoa vê as alterações antes de elas chegarem à main e pega erros que o autor deixou passar;
• verificações automáticas: o GitHub Actions ou outro CI roda testes e linters em cada PR, e um status vermelho impede mesclar código quebrado;
• histórico de decisões: daqui a um ano, pelo PR dá para entender não só o que foi alterado, mas também o porquê, com a discussão;
• contribuição para projetos alheios: em open source você não tem permissão de escrita, e o PR a partir de um fork é a única forma de propor uma correção;
• proteção de branches: as regras de proteção do GitHub podem proibir o push direto na main e exigir um PR aprovado.

Como criar um pull request no GitHub a partir de uma branch

Esse é o cenário típico de uma equipe em que todos têm permissão de escrita no repositório. O trabalho acontece em uma branch de funcionalidade, e a main muda somente por PR.

Passo 1. Crie uma branch a partir de uma main atualizada

git switch main
git pull
git switch -c feature/login-form

Dê à branch um nome descritivo: feature/…, fix/…, número da tarefa. Assim o revisor entende do que se trata antes de abrir qualquer coisa.

Passo 2. Faça os commits

git add src/login.js
git commit -m "Adiciona formulário de login"

Um PR, uma tarefa. Um PR pequeno, de 100 a 300 linhas, é revisado rápido e com atenção; com 3000 linhas, o revisor aprova sem olhar direito.

Passo 3. Envie a branch ao servidor (git push para o pull request)

git push -u origin feature/login-form

A opção -u vincula a branch local à remota, e daí em diante basta git push. A resposta do GitHub traz o link para criar o PR:

remote: Create a pull request for 'feature/login-form' on GitHub by visiting:
remote:      https://github.com/equipe/app/pull/new/feature/login-form

Passo 4. Abra o PR na interface web

Acesse o link do terminal ou abra o repositório no GitHub: depois de um push recente aparece um aviso com o botão «Compare & pull request». Outro caminho é a aba «Pull requests» e o botão «New pull request».

1. Confira o par de branches: base é o destino da mesclagem (normalmente main) e compare é a sua branch.
2. Escreva um título que diga o que foi feito, de forma breve e no imperativo.
3. Na descrição, explique o motivo, como testar e o que ficou fora do escopo. Se o repositório tem um modelo de PR, os campos são preenchidos automaticamente.
4. À direita, atribua revisores (Reviewers), responsáveis (Assignees) e etiquetas, se a equipe usar.
5. Clique em «Create pull request» ou escolha a opção de rascunho, sobre a qual falamos abaixo.

Criar um PR pelo terminal: GitHub CLI

Se você não quer trocar para o navegador, existe a ferramenta oficial gh. Não é um comando do Git, mas um programa do GitHub; para PRs, é bem prático:

gh pr create --base main --title "Adiciona formulário de login" --body "Closes #42"
gh pr list
gh pr checkout 57
gh pr merge 57 --squash

Se você procura «comandos git pull request», a resposta honesta é: o Git cuida de branches, commits e push, enquanto o PR é criado na plataforma — no navegador, com gh ou pela API.

Como fazer um pull request para um repositório alheio usando fork

Em projetos abertos você não tem permissão de escrita. Por isso, primeiro você faz um fork, uma cópia do repositório na sua conta do GitHub; trabalha nela e propõe as alterações ao original.

1. Na página do projeto, clique em «Fork»: você terá github.com/seu-usuario/projeto.
2. Clone o seu fork e adicione o original como um segundo remote, normalmente chamado upstream.
3. Crie uma branch, faça os commits e envie a branch para o seu fork.
4. No GitHub, abra o PR: repositório base, o projeto original; repositório head, o seu fork com a sua branch.

git clone git@github.com:seu-usuario/projeto.git
cd projeto
git remote add upstream https://github.com/dono/projeto.git
git switch -c fix/typo-readme
git commit -am "Corrige erro de digitação no README"
git push -u origin fix/typo-readme

Antes de começar, veja o arquivo CONTRIBUTING.md: normalmente ele descreve as regras para as mensagens de commit, os testes e se é preciso abrir uma issue antes. Mantenha o fork atualizado com git fetch upstream e git rebase upstream/main na sua branch, para que o PR não fique para trás do original.

Merge request no GitLab: o que é e como criar

O merge request da plataforma GitLab é o equivalente completo do pull request. Mudam os nomes e alguns detalhes da interface, mas o processo é o mesmo: branch, push, pedido de mesclagem, revisão e mesclagem.

Você pode criar um MR de algumas formas:

• pelo link que o GitLab mostra no terminal depois de um git push de uma branch nova;
• na seção Merge requests do projeto, com o botão «New merge request», escolhendo a branch de origem e a de destino;
• diretamente no push, com as opções de push do GitLab, sem abrir o navegador.

git push -o merge_request.create -o merge_request.target=main origin feature/login-form

A terminologia do GitLab é um pouco diferente: a aprovação se chama approve, o responsável pela mesclagem é o assignee, e em vez do GitHub Actions é usado o GitLab CI/CD com o arquivo .gitlab-ci.yml. Os rascunhos também existem e se chamam Draft.

Revisão de um pull request

O revisor abre a aba «Files changed» e vê o diff. Pode deixar um comentário em qualquer linha ou propor uma alteração pronta (suggestion), que o autor aplica com um botão. Os comentários são agrupados em uma revisão e enviados juntos com um destes veredictos:

• Comment: observações sem decisão;
• Approve: as alterações estão aprovadas;
• Request changes: é preciso ajustar; não convém mesclar ainda.

Uma boa revisão olha a lógica, a legibilidade, os testes e os casos extremos, em vez de discutir gosto pessoal: a formatação é melhor deixar para o linter no CI. O autor deve responder a cada comentário: corrigi, conversamos ou mantemos assim, com uma explicação.

Como testar um PR alheio localmente (git checkout pull request)

Às vezes é preciso executar o código na sua máquina. Se a branch está no mesmo repositório, basta git fetch e git switch. Para um PR vindo de um fork, o GitHub oferece referências especiais pull/<número>/head:

git fetch origin pull/57/head:pr-57
git switch pr-57

No GitLab, as referências equivalentes se chamam merge-requests/<número>/head. Ou simplesmente gh pr checkout 57, se você tiver o GitHub CLI.

Como atualizar um pull request depois dos comentários

O PR está ligado à branch, não a commits específicos. Basta fazer commits novos na mesma branch e enviá-los: o PR é atualizado sozinho, sem criar uma nova solicitação.

git commit -am "Atende aos comentários da revisão"
git push

Git rebase em um pull request: trazer a main atualizada

Enquanto o PR aguarda revisão, a main avança. Se o GitHub indicar que a branch está desatualizada ou houver conflitos, atualize-a. A opção com rebase deixa o histórico linear:

git fetch origin
git rebase origin/main
# resolver conflitos, git add, git rebase --continue
git push --force-with-lease

Depois de um rebase, os hashes dos commits mudam, então um push comum é recusado e é preciso um forçado. Use --force-with-lease: ele não sobrescreve a branch se nela apareceram commits de outras pessoas. Se várias pessoas trabalham na branch, é mais seguro incorporar a main com git merge origin/main, sem reescrever o histórico.

Como mesclar um pull request: merge, squash e rebase

Quando a revisão está aprovada e as verificações estão verdes, o PR pode ser mesclado. O GitHub oferece três formas, e o administrador do repositório pode deixar apenas algumas delas.

Mesclar o pull request pela interface equivale ao git merge normal, só que executado no servidor. Depois da mesclagem, o GitHub sugere excluir a branch: aceite, ela não é mais necessária. No seu computador, limpe o que é local:

git switch main
git pull
git branch -d feature/login-form

Também é possível mesclar manualmente pelo terminal: integrar a branch à main localmente e fazer push. O GitHub percebe que os commits da branch já estão na base e marca o PR como mesclado. Mas assim as verificações e as regras de proteção são ignoradas, por isso, em equipes, a mesclagem costuma ser feita pelo botão.

Auto-merge e fila de mesclagem

Se as verificações demoram, é possível ativar a mesclagem automática: o PR será mesclado sozinho quando todas as condições forem atendidas. Em repositórios grandes, usa-se uma fila de mesclagem (merge queue), que testa cada PR sobre os que já estão na fila, para que a main não quebre por mudanças incompatíveis entre si.

Rascunhos de pull request (Draft)

Um rascunho é um PR que ainda não está pronto para revisão. Ele não pode ser mesclado, e os revisores não recebem o pedido de revisão. Rascunhos são úteis para mostrar cedo a direção do trabalho, executar o CI ou colher opiniões sobre a arquitetura. No GitHub, ao criar o PR, escolha a opção de rascunho no menu suspenso do botão de criação, ou execute gh pr create --draft. Quando o trabalho estiver concluído, clique em «Ready for review». No GitLab, o rascunho é marcado com o prefixo Draft: no título do MR.

Relação do pull request com as issues

Se na descrição do PR você escrever uma palavra-chave seguida do número da tarefa, o GitHub fechará a issue automaticamente depois que o PR for mesclado na branch padrão:

Closes #42
Fixes #17
Resolves #8

Funcionam as palavras close, fix e resolve em suas várias formas (closes, fixed, resolves). A simples menção #42, sem palavra-chave, cria um link, mas não fecha a tarefa. No GitLab, funcionam de forma parecida Closes #42 e frases semelhantes.

Dá para excluir um pull request ou merge request?

Um participante comum não consegue excluir um PR no GitHub: só fechá-lo, com o botão «Close pull request». O PR fechado permanece no histórico e pode ser reaberto. A branch, depois de fechar o PR, deve ser excluída separadamente. Remover o PR por completo só é possível pelo suporte do GitHub, por exemplo se nele foram publicados segredos.

No GitLab, o MR pode ser fechado pelo autor ou por um membro com permissão, e excluído pelo dono do projeto ou por um administrador. Se uma senha ou um token foi parar em um PR, fechá-lo não basta: revogue o segredo imediatamente, porque os commits já estiveram no servidor.

Erros típicos com pull requests

• PR a partir da main. Você fez commits na sua main local e abriu o PR a partir dela. Os PRs seguintes vão carregar aquelas mudanças antigas. Trabalhe sempre em uma branch separada.
• Branch base errada. O PR foi aberto contra develop em vez de main, ou o contrário. A base é alterada pelo botão Edit ao lado do título do PR.
• Arquivos a mais no diff. Builds, node_modules, .env. Adicione-os ao .gitignore e retire-os do índice com git rm --cached.
• PR enorme. Divida a tarefa em vários PRs encadeados.
• Push comum depois de um rebase. Erro rejected (non-fast-forward). É preciso git push --force-with-lease, e não --force.
• Conflitos resolvidos às cegas no editor web. Atualize a main localmente, resolva o conflito e teste.

Pull request no git flow e em outros processos

O pull request se encaixa em qualquer processo de equipe. No GitHub Flow é simples: branch a partir da main, PR, revisão, mesclagem e deploy. No git flow, os PRs são abertos para develop a partir das branches de funcionalidade, e as branches de release e hotfix também passam por um PR para a main. No desenvolvimento baseado em trunk, os PRs são curtos e duram horas, não dias. Qualquer que seja o processo, a regra é uma só: alterações em branches compartilhadas entram somente por pull request.

Resumo

O pull request é um mecanismo da plataforma, não um comando do Git: uma branch enviada ao servidor mais uma página com discussão, revisão e verificações. No GitLab ele se chama merge request; na conversa, diz-se PR ou MR. Crie o PR a partir de uma branch separada, mantenha-o pequeno, atualize-o com push na mesma branch e escolha o método de mesclagem de acordo com o histórico que você quer ter. Branches de funcionalidade, forks e pull requests são explicados com prática no curso de Git.