Merge Request (MR): o que é, como criar e o processo de revisão

O que é um Merge Request (MR)?

Merge Request (MR) — uma solicitação para integrar alterações de um branch Git em outro, que inicia o processo de revisão de código e verificações automatizadas. Ao contrário da mesclagem direta via console, o MR cria um procedimento formal: o desenvolvedor descreve as alterações, atribui revisores, inicia CI/CD e recebe feedback antes da aplicação das alterações. Este é um elemento-chave do GitLab, mas o mecanismo equivalente no GitHub é chamado Pull Request (PR).

De acordo com GitLab Documentation, 2026, mais de 80 milhões de Merge Requests são criados no GitLab anualmente. Cada MR contém quatro componentes principais: uma descrição com o contexto das alterações, uma lista de commits, a diferença de código (diff) e discussão (thread de discussão). Sem um desses elementos, o MR é considerado incompleto.

Merge Request (MR) resolve três tarefas: evita alterações diretas em branches protegidos (main, develop), fornece controle de qualidade através da revisão e preserva o histórico de discussões para futuros desenvolvedores. No GitLab, o status do MR é exibido na interface com indicadores de cor: cinza para Draft, laranja para pendente, verde para Approved, roxo para Merged e vermelho para Closed.

Terminologia: MR, PR e CR

Em diferentes plataformas Git, Merge Request é chamado de formas diferentes. GitLab usa “Merge Request” (MR), GitHub usa “Pull Request” (PR). A analogia é Change Request (CR) no Gerrit. Todos os três denotam o mesmo processo: uma solicitação para integrar alterações através de revisão de código. A escolha do termo depende apenas da plataforma usada no projeto.

# Criar um branch com alterações
git checkout -b feature/add-auth
git commit -m "Add OAuth2 authentication flow"
git push origin feature/add-auth

# Você pode criar um MR via UI do GitLab/GitHub ou CLI:
gh pr create --title "Add OAuth2 authentication flow" \
  --body "Implements OAuth2 with Google and Apple providers" \
  --reviewer "team-lead"

MR vs PR: qual a diferença entre GitLab e GitHub

Merge Request no GitLab e Pull Request no GitHub são mecanismos funcionalmente idênticos com nomes diferentes. A diferença se deve à história: GitLab originalmente se posicionou como uma alternativa Self-Hosted ao GitHub e escolheu o termo “merge request” para o processo de mesclagem. GitHub, lançado antes, usou “pull request” — uma solicitação para “puxar” (pull) as alterações para o branch principal.

De acordo com GitHub Docs, 2024, ambas as ferramentas suportam o mesmo conjunto de recursos: descrição em Markdown, atribuição de revisores, comentários em linhas específicas de código, status de verificação e mesclagem automática quando as condições são atendidas. As diferenças dizem respeito à interface e capacidades adicionais.

Como criar um Merge Request: guia passo a passo

Criar um Merge Request (MR) começa com a publicação de um branch com alterações no repositório remoto. Após o push para GitLab ou GitHub, a interface mostra um botão “Create Merge Request” ou “Compare & Pull Request”. O desenvolvedor preenche a descrição, especifica o branch de destino (geralmente develop ou main), atribui revisores e anexa labels.

De acordo com GitLab Documentation, 2025, um MR padrão contém um título de até 72 caracteres, uma descrição com template e um link para a issue. A descrição deve responder às perguntas: o que foi feito, por que, como foi testado. GitLab suporta o fechamento automático de issues ao mesclar através das palavras-chave Closes, Fixes, Resolves.

# Exemplo de template .gitlab/merge_request_templates/default.md
## What does this MR do?

[Breve descrição das alterações: o quê e por quê]

## How to test

1. Executar ./gradlew test
2. Verificar LoginActivity com token de teste
3. Garantir que não há regressão em AuthManager

## Related issues

Closes #142

Ciclo de vida do MR: do Draft ao Merged

Merge Request (MR) passa por cinco status no GitLab. O primeiro é Draft (rascunho), marcado com o prefixo “Draft:” no título, que bloqueia a mesclagem. Quando pronto, o desenvolvedor remove o Draft e o MR transita para o status Opened — a revisão de código começa e o pipeline CI/CD é iniciado.

De acordo com GitLab Docs, 2024, no status Opened, os revisores examinam o diff, deixam comentários e solicitam alterações através de Resolve Threads. Quando todos os threads são resolvidos e CI/CD passa com sucesso, o desenvolvedor responsável define Approve. Depois disso, o MR pode ser mesclado usando o botão Merge, ou pode-se aguardar a mesclagem automática (Auto-merge).

GitLab suporta três opções de status final: Merged (mesclado com sucesso), Closed (fechado sem mesclagem, por exemplo, ao abandonar uma funcionalidade) e Reopened (reabertura após fechamento). Cada status é registrado na Linha do Tempo de Atividade do MR para auditoria.

Status automáticos e gatilhos

GitLab atualiza automaticamente o status do Merge Request mediante eventos: o push de novos commits redefine as Approvals, ao passar no pipeline CI o status se torna Pipeline passed, ao falhar — Pipeline failed (a mesclagem é bloqueada). Pode-se configurar Auto-merge: o MR é mesclado automaticamente após CI bem-sucedido e recebimento de todas as aprovações necessárias.

• Draft — rascunho, CI executa mas mesclagem bloqueada
• Opened — pronto para revisão, revisores atribuídos, pipeline ativo
• Approved — número necessário de aprovações recebido
• Merged — alterações mescladas no branch de destino
• Closed — fechado sem mesclagem

Regras de revisão de código no Merge Request

A revisão de código no Merge Request (MR) é uma etapa obrigatória na maioria dos projetos comerciais. De acordo com a pesquisa SmartBear, 2023, a revisão de código com MR reduz o número de defeitos em 30–60% e acelera a integração de novos desenvolvedores. A regra principal é que cada MR seja verificado por pelo menos um, de preferência dois desenvolvedores que não participaram da escrita do código.

A revisão de MR inclui cinco critérios: correção lógica, conformidade com o estilo de código, cobertura de testes, segurança e desempenho. No GitLab, é possível configurar Required Approvals — o número obrigatório de aprovações antes da mesclagem, por exemplo, 2 aprovações para main e 1 para develop.

A discussão no MR é conduzida em Threads — comentários em linhas específicas de código. Cada thread deve ser resolvido antes da mesclagem. Para acelerar as revisões, recomenda-se limitar o tamanho do MR: 200–400 linhas de alterações. De acordo com Google Research (2022), MRs com mais de 400 linhas são revisados 30% menos efetivamente.

Pipeline CI/CD no Merge Request

Ao criar um Merge Request (MR), o pipeline CI/CD é iniciado automaticamente. No GitLab isso acontece através do arquivo .gitlab-ci.yml, no GitHub através do workflow do GitHub Actions. O pipeline inclui build do projeto, testes unitários, linters, análise estática (SAST) e verificação de cobertura de código.

De acordo com GitLab Blog, 2024, o status do pipeline é exibido diretamente no MR: marca verde (passed), cruz vermelha (failed) ou círculo amarelo (running). Se o pipeline falhar, GitLab bloqueia o botão Merge até a correção. Nas configurações, pode-se habilitar “Merge when pipeline succeeds” — mesclagem automática após um pipeline bem-sucedido.

# .gitlab-ci.yml — exemplo para um projeto Android
test:
  stage: test
  script:
    - ./gradlew ktlintCheck
    - ./gradlew testDebugUnitTest
  only:
    - merge_requests

build:
  stage: build
  script:
    - ./gradlew assembleDebug
  only:
    - merge_requests

Métodos de mesclagem: Squash, Merge Commit, Fast-Forward

GitLab e GitHub oferecem três métodos de mesclagem para Merge Request. A escolha depende da política da equipe e da limpeza desejada do histórico. Merge Commit cria um commit de mesclagem separado, preservando todo o histórico do branch de funcionalidade. Squash combina todos os commits do branch em um único commit no branch de destino. Fast-Forward aplica os commits linearmente sem um commit de mesclagem.

De acordo com GitLab Docs, 2025, Squash é preferível para projetos com alta densidade de commits (20+ commits em um branch de funcionalidade). Fast-Forward é obrigatório para Trunk-Based Development. Merge Commit é usado no Git Flow para preservar a semântica de ramificação.

• Merge Commit — preserva o histórico, cria um commit de mesclagem, adequado para Git Flow
• Squash — combina todos os commits em um, histórico limpo, perde commits intermediários
• Fast-Forward — histórico linear sem commit de mesclagem, obrigatório em TBD

Melhores práticas: como escrever um bom MR

Um Merge Request (MR) de qualidade reduz o tempo de revisão e o número de erros. A primeira regra é que um MR resolve uma tarefa. Se as alterações afetam múltiplas funcionalidades não relacionadas, elas devem ser divididas em MRs separados. Segundo, o título do MR deve ser informativo: “Add OAuth2 authentication with Google provider” em vez de “Fix stuff” ou “Update code”.

De acordo com Google Engineering Practices, 2024, um bom MR contém uma descrição do contexto: por que as alterações são necessárias, como foram testadas e quais riscos existem. O tamanho do MR não deve exceder 400 linhas de alterações. Se o volume for maior, a tarefa precisa ser decomposta em subtarefas. Para documentação e testes, exceções são aceitáveis mas com explicação.

Merge Request (MR) deve incluir testes automatizados para a nova funcionalidade. No GitLab, é possível configurar a política Coverage Check — o MR é automaticamente bloqueado se a cobertura de código cair abaixo de um limite (por exemplo, 80%). Isso garante que a nova funcionalidade não reduza a qualidade geral do projeto.

• Um MR — uma tarefa: decomponha alterações grandes em vários MRs pequenos
• Descrição com template: use .gitlab/merge_request_templates para uniformidade
• Tamanho até 400 linhas: MRs grandes são revisados mais lentamente e com mais erros
• Testes obrigatórios: novas funcionalidades devem ser cobertas por testes unitários

Templates de descrição de MR

GitLab suporta templates de Merge Request através de arquivos .gitlab/merge_request_templates/. O template inclui seções: o que foi feito, como testar, tarefas relacionadas e checklist. O uso de templates acelera a criação de MRs e garante que os desenvolvedores não esqueçam de incluir informações importantes. Na descrição do MR, devem ser especificadas as issues relacionadas (Closes #N) para fechamento automático de tarefas ao mesclar.