Merge Request (MR)：是什么，如何创建以及审查流程

什么是 Merge Request (MR)？

Merge Request (MR) — 将更改从一个 Git 分支集成到另一个分支的请求，启动代码审查和自动检查过程。与通过控制台直接合并不同，MR 创建了正式程序：开发人员描述更改、指定审查者、启动 CI/CD 并在应用更改前获得反馈。这是 GitLab 的关键元素，但 GitHub 中的类似机制称为 Pull Request (PR)。

根据 GitLab Documentation, 2026，GitLab 每年创建超过 8000 万个 Merge Request。每个 MR 包含四个主要组件：带有更改上下文的描述（description）、提交列表（commits）、代码差异（diff）和讨论（discussion thread）。缺少其中一个元素，MR 被视为不完整。

Merge Request (MR) 解决三个任务：防止对受保护分支（main、develop）的直接更改、通过审查确保质量控制、以及为未来的开发人员保留讨论历史。在 GitLab 中，MR 状态在界面中以颜色指示显示：灰色为 Draft，橙色为等待，绿色为 Approved，紫色为 Merged，红色为 Closed。

术语：MR、PR 和 CR

在不同的 Git 平台上，Merge Request 有不同的名称。GitLab 使用 “Merge Request” (MR)，GitHub 使用 “Pull Request” (PR)。类似地 — Gerrit 中的 Change Request (CR)。三者都表示相同的过程：通过代码审查集成更改的请求。术语的选择仅取决于项目中使用的平台。

# 创建带有更改的分支
git checkout -b feature/add-auth
git commit -m "Add OAuth2 authentication flow"
git push origin feature/add-auth

# 可以通过 GitLab/GitHub UI 或 CLI 创建 MR：
gh pr create --title "Add OAuth2 authentication flow" \
  --body "Implements OAuth2 with Google and Apple providers" \
  --reviewer "team-lead"

MR 与 PR：GitLab 和 GitHub 之间的区别

Merge Request 在 GitLab 和 Pull Request 在 GitHub — 是功能相同但名称不同的机制。区别源于历史：GitLab 最初定位为 GitHub 的 Self-Hosted 替代方案，并为合并过程选择了 “Merge Request” 这一术语。较早启动的 GitHub 使用了 “Pull Request” — 将更改 “拉取” (pull) 到主分支的请求。

根据 GitHub Docs, 2024，两种工具支持相同的功能集：Markdown 描述、指定审查者、对特定代码行进行评论、检查状态以及在满足条件时自动合并。差异涉及界面和附加功能。

如何创建 Merge Request：分步指南

创建 Merge Request (MR) 始于将包含更改的分支发布到远程仓库。推送到 GitLab 或 GitHub 后，界面中出现 “Create Merge Request” 或 “Compare & Pull Request” 按钮。开发人员填写描述、指定目标分支（通常是 develop 或 main）、指定审查者并添加标签（labels）。

根据 GitLab Documentation, 2025，标准 MR 包含最多 72 个字符的标题、带有模板（template）的描述以及指向任务（issue）的链接。描述应回答以下问题：做了什么、为什么、如何测试。GitLab 支持通过关键词 Closes、Fixes、Resolves 在合并时自动关闭 issue。

# .gitlab/merge_request_templates/default.md 模板示例
## What does this MR do?

[更改的简要说明：什么和为什么]

## How to test

1. 运行 ./gradlew test
2. 检查 LoginActivity 使用测试 token
3. 确保在 AuthManager

## Related issues

Closes #142

MR 生命周期：从 Draft 到 Merged

Merge Request (MR) 在 GitLab 中经历五种状态。第一种 — Draft（草稿），标题中以 “Draft:” 前缀标记并阻止合并。准备就绪后，开发人员移除 Draft，MR 进入 Opened 状态 — 代码审查开始，CI/CD 管道启动。

根据 GitLab Docs, 2024，在 Opened 状态下，审查者查看 diff、留下评论并通过 Resolve Threads 请求更改。当所有线程关闭且 CI/CD 成功通过后，负责的开发人员设置 Approve。之后，MR 可以通过 Merge 按钮合并，或等待自动合并（Auto-merge）。

GitLab 支持三种最终状态变体：Merged（成功合并）、Closed（未合并关闭，例如放弃功能时）和 Reopened（关闭后重新打开）。每个状态都会记录在 Activity Timeline MR 中用于审计。

自动状态和触发器

GitLab 在事件发生时自动更新 Merge Request 状态：推送新提交时 Approvals 重置，CI 管道成功时状态变为 Pipeline passed，出错时 — Pipeline failed（合并被阻止）。可以配置 Auto-merge：MR 在 CI 成功并获得所有必要批准后自动合并。

• Draft — 草稿，CI 运行但合并被阻止
• Opened — 准备好审查，已指定审查者，管道活跃
• Approved — 已获得所需的批准数量
• Merged — 更改已合并到目标分支
• Closed — 未合并关闭

Merge Request 中的代码审查规则

Merge Request (MR) 中的代码审查 — 大多数商业项目中的强制阶段。根据 SmartBear, 2023 的研究数据，通过 MR 进行代码审查可将缺陷数量减少 30–60%，并加速新开发人员的入职。主要规则 — 每个 MR 至少由一名（最好两名）未参与编写代码的开发人员检查。

MR 检查 包括五个标准：逻辑正确性、代码风格符合性、测试覆盖率、安全性和性能。在 GitLab 中可以配置 Required Approvals — 合并前必须获得的批准数量，例如 main 需要 2 个批准，develop 需要 1 个。

MR 中的讨论 在线程（Threads）中进行 — 对特定代码行的评论。每个线程必须在合并前 resolved（关闭）。为加快审查，建议限制 MR 大小：200–400 行更改。根据 Google Research (2022) 的数据，超过 400 行的 MR 审查效率降低 30%。

Merge Request 中的 CI/CD 管道

创建 Merge Request (MR) 时，CI/CD 管道会自动启动。在 GitLab 中，这是通过 .gitlab-ci.yml 文件实现的，在 GitHub 中 — 通过 GitHub Actions workflow。管道包括项目构建（build）、运行单元测试（unit tests）、linter（lint）、静态分析（SAST）和代码覆盖率检查。

根据 GitLab Blog, 2024，管道状态直接显示在 MR 中：绿色勾（passed）、红色叉（failed）或黄色圆（running）。如果管道失败，GitLab 会阻止 Merge 按钮直到修复。在设置中可以启用 “Merge when pipeline succeeds” — 管道成功后自动合并。

# .gitlab-ci.yml — Android 项目示例
test:
  stage: test
  script:
    - ./gradlew ktlintCheck
    - ./gradlew testDebugUnitTest
  only:
    - merge_requests

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

合并方法：Squash、Merge Commit、Fast-Forward

GitLab 和 GitHub 为 Merge Request 提供三种合并方法。选择取决于团队策略和所需的历史记录清晰度。Merge Commit — 创建单独的合并提交，保留功能分支的完整历史记录。Squash — 将分支的所有提交合并为目标分支上的一个提交。Fast-Forward — 线性应用提交，没有合并提交。

根据 GitLab Docs, 2025，Squash 在提交密度高的项目中（一个功能分支中有 20 个以上提交）更受青睐。Fast-Forward 对于 Trunk-Based Development 是强制性的。Merge Commit 在 Git Flow 中用于保留分支语义。

• Merge Commit — 保留历史记录，创建合并提交，适合 Git Flow
• Squash — 将所有合并为一个，历史干净，中间提交丢失
• Fast-Forward — 无合并提交的线性历史，TBD 中强制使用

最佳实践：如何写好 MR

高质量的 Merge Request (MR) 可以缩短审查时间并减少错误数量。第一条规则 — 一个 MR 解决一个任务。如果更改涉及多个不相关的功能，应将其拆分为单独的 MR。第二条 — MR 标题应具有信息性：使用 “Add OAuth2 authentication with Google provider” 而不是 “Fix stuff” 或 “Update code”。

根据 Google Engineering Practices, 2024，好的 MR 包含上下文描述：为什么需要更改、如何测试、有哪些风险。MR 的大小不应超过 400 行更改。如果体积更大 — 任务应分解为子任务。对于文档和测试，允许例外，但需要解释。

Merge Request (MR) 应包含新功能的自动化测试。在 GitLab 中可以配置 Coverage Check 策略 — 如果代码覆盖率低于阈值（例如 80%），MR 会自动阻止。这确保新功能不会降低项目的整体质量。

• 一个 MR — 一个任务：将大型更改分解为多个小型 MR
• 使用模板的描述：使用 .gitlab/merge_request_templates 保持一致性
• 大小不超过 400 行：大型 MR 审查速度较慢且错误较多
• 测试必须：新功能应包含单元测试

MR 描述模板

GitLab 通过 .gitlab/merge_request_templates/ 文件支持 Merge Request 模板。模板包含部分：做了什么、如何测试、相关任务和检查清单。使用模板可以加速 MR 创建并确保开发人员不会忘记提供重要信息。在 MR 描述中必须指明相关 issue（Closes #N），以便在合并时自动关闭任务。