Pull Request: o que é, processo de criação e code review

O que é um Pull Request?

Pull Request (PR) é uma solicitação formal para incluir alterações de um branch para outro em um sistema de controle de versão distribuído. O PR é um elemento central do desenvolvimento colaborativo nas plataformas GitHub, GitLab e Bitbucket, combinando discussão de código, testes automatizados e o processo de aprovação de alterações.

O nome “Pull Request” reflete a essência da operação: um desenvolvedor pede (request) ao proprietário do repositório para “puxar” (pull) suas alterações. O termo foi introduzido pelo GitHub em 2008 — antes disso, um mecanismo similar existia na forma de patches e merge requests (termo do GitLab). Hoje, o PR é o padrão de facto para desenvolvimento em equipe com Git.

De acordo com o GitHub Octoverse, 2025, 89% dos projetos open-source exigem a criação de um PR para fazer alterações. No desenvolvimento corporativo, esse número chega a 95%. O PR se tornou não apenas uma ferramenta técnica, mas parte da cultura de desenvolvimento: através dos PRs ocorrem a transferência de conhecimento, detecção de bugs e alinhamento de decisões arquiteturais.

Componentes de um Pull Request

Um PR típico consiste em um título, descrição, lista de arquivos alterados (diff), comentários dos revisores e status das verificações CI. Cada PR está vinculado a um branch de origem e um branch de destino específicos, e após a mesclagem pode ser excluído automaticamente.

Como criar um Pull Request

Criar um PR começa com a publicação de um branch de funcionalidade no repositório remoto. Após o push, o desenvolvedor abre um PR através da interface da plataforma ou via CLI (gh, glab). Vamos ver o processo usando o GitHub como exemplo.

Push do branch e abertura do PR

O primeiro passo é fazer push do branch de funcionalidade para o repositório remoto e criar um Pull Request através da interface web ou linha de comando.

# Criar e enviar um branch de funcionalidade
git checkout -b feature/biometric-auth
git add src/auth/
git commit -m "feat: add biometric authentication"
git push -u origin feature/biometric-auth

# Criar um PR via GitHub CLI
gh pr create --title "feat: add biometric authentication" \
  --body "Implements fingerprint and face recognition login.
  Closes #142" \
  --base develop

Após criar um PR, o GitHub executa automaticamente os pipelines de CI (GitHub Actions), verifica conflitos com o branch de destino e convida revisores. O template de descrição do PR pode ser configurado via .github/PULL_REQUEST_TEMPLATE.md para que todos os PRs contenham as seções necessárias: objetivo, alterações, testes, tarefas relacionadas.

Descrição e marcação

Uma descrição de PR de qualidade inclui: um link para a tarefa (issue/ticket), uma breve descrição das alterações, instruções de teste e uma lista de alterações relacionadas. Labels (bug, feature, refactoring) ajudam a categorizar o PR, enquanto assignees e reviewers são atribuídos automaticamente via CODEOWNERS.

# Atribuir revisores via CODEOWNERS (arquivo na raiz do repositório)
# Exemplo .github/CODEOWNERS:
# src/auth/ @team-auth @senior-dev
# src/api/ @team-backend
# *.kt @kotlin-team

# Criar um PR atribuindo revisores via gh cli
gh pr create --reviewer "team-auth" --label "feature"

CODEOWNERS é um mecanismo padrão do GitHub/GitLab para atribuir revisores automaticamente com base nos arquivos alterados. Por exemplo, qualquer alteração no diretório src/auth/ atribui automaticamente team-auth e senior-dev como revisores. Isso acelera o processo e garante que as pessoas certas vejam o PR.

Atualização do PR com base nas revisões

Após receber os comentários do revisor, o desenvolvedor faz correções no mesmo branch de funcionalidade e faz push de novos commits — o PR é atualizado automaticamente. É importante não reescrever o histórico (rebase) em um branch de funcionalidade publicado se o PR já estiver aberto, pois isso quebra os links para commits específicos nos comentários.

# Fazer alterações com base nos comentários do revisor
git checkout feature/biometric-auth
# corrigir o código
git commit -m "fix: handle biometric timeout per review"
git push

# o PR será atualizado automaticamente
# Após a aprovação — mesclar o PR através da interface do GitHub

O processo de code review

O code review é um elemento central de um Pull Request. O revisor verifica as alterações quanto à correção, estilo de código, segurança e consistência arquitetural. Uma revisão de qualidade não apenas previne bugs, mas também dissemina conhecimento sobre a base de código dentro da equipe.

As Engineering Practices do Google (2025) recomendam os seguintes princípios de code review: o revisor deve entender o contexto das alterações, dar recomendações específicas em vez de comentários gerais e separar comentários técnicos e estilísticos. O tempo de revisão não deve exceder 24 horas a partir do momento da criação do PR.

Para o desenvolvimento mobile, o code review inclui verificações específicas: compatibilidade com targetSdk, tratamento correto do lifecycle (Android) / view lifecycle (iOS), ausência de vazamentos de memória (LeakCanary, Instruments), suporte a tema escuro e localização. Essas verificações podem ser automatizadas através de linters e Detekt/ktlint.

Tipos de comentários

As plataformas de PR suportam três tipos de comentários: gerais (ao PR inteiro), em linha (a uma linha específica de código) e sugestões (com código de substituição). As sugestões permitem aplicar a alteração com um clique, acelerando o processo e reduzindo o número de iterações.

Depois que todos os comentários são resolvidos e as verificações CI passam, o revisor envia uma aprovação (Approved). O PR pode ser mesclado. GitHub e GitLab suportam regras de proteção de branch: número necessário de aprovações, verificações CI obrigatórias e proibição de push para main sem PR. Para projetos mobile, a proteção de branch também inclui verificação de build: um PR não pode ser mesclado se o aplicativo não compilar (gradle build failed / xcodebuild failed).

Resolução de conflitos no PR

Conflitos de mesclagem em um Pull Request são uma situação comum no trabalho em equipe ativo. As plataformas oferecem resolução de conflitos através da interface web (para conflitos simples) ou recomendam resolver localmente. GitHub Actions verifica automaticamente a capacidade de mesclagem a cada push no branch de funcionalidade e marca o PR como conflituoso se a mesclagem não for possível.

Melhores práticas de Pull Request

Pull Requests eficazes aceleram o code review e reduzem o número de bugs. Um estudo da SmartBear (2025) mostrou que PRs de até 200 linhas de código recebem 2 vezes mais comentários significativos do que PRs com mais de 1000 linhas, e o tempo de revisão é reduzido em 3 vezes.

• PRs pequenos — o tamanho ideal é de 100 a 300 linhas. Divida PRs grandes em partes lógicas: cada PR resolve uma tarefa. Isso simplifica a revisão e reduz a probabilidade de conflitos
• Descrição clara — título de acordo com Conventional Commits (feat:, fix:, refactor:), o corpo contém “o que e por quê” em vez de “como” (o código fala por si). Template: objetivo → alterações → testes → issues relacionadas
• Feedback rápido — revisão dentro de 24 horas. Se um PR espera mais de um dia, a equipe perde contexto e o número de conflitos de mesclagem aumenta
• Automação — linters, formatadores e testes devem ser executados automaticamente ao criar um PR. Não permita mesclar PRs com verificações CI vermelhas
• Draft PR — use para discussão antecipada de arquitetura. O Draft PR não requer revisão e não pode ser mesclado, mas permite mostrar o código aos colegas em um estágio inicial

Práticas adicionais: não crie PRs na sexta-feira à noite (ninguém revisará até segunda-feira), solicite revisão de 1 a 2 pessoas (mais pessoas retardam o processo sem melhorar a qualidade), use squash merge para comprimir o histórico antes da mesclagem. Para projetos mobile, também é recomendado adicionar um link para o build de teste (Firebase App Distribution / TestFlight) na descrição do PR para que o revisor possa verificar as alterações no aplicativo em execução.

Pull Request em diferentes plataformas

As principais plataformas para trabalhar com Pull Requests são GitHub, GitLab e Bitbucket. Apesar do conceito compartilhado, cada uma tem características que valem a pena considerar ao escolher uma ferramenta para a equipe.

GitHub é a plataforma mais popular com a maior comunidade, Actions para CI/CD e um ecossistema extenso de aplicativos (GitHub Marketplace). GitLab se destaca pelo CI/CD integrado e capacidade de implantação self-hosted completa. Bitbucket é fortemente integrado com Jira e o ecossistema Atlassian, popular em ambientes corporativos.

Para o desenvolvimento mobile, a escolha da plataforma é frequentemente determinada pelas capacidades de CI/CD: GitHub Actions suporta runners macOS para builds iOS, GitLab tem runners integrados para iOS/Android, Bitbucket se integra bem com Firebase Test Lab. Independentemente da plataforma, o processo de PR permanece o mesmo: branch → revisão → CI → mesclagem.