GitLab Merge Request 实战指南：从分支管理到代码审查的完整流程

我第一次在GitLab上发起Pull Request，是在刚进团队没多久的时候。那时候大家还习惯直接往 develop 分支推代码，觉得流程越短越高效。直到有次我改了一个配置项，没经过任何人 review 就推了上去，结果测试环境整个服务起不来。主管在群里问"谁动了配置"，我战战兢兢承认之后，他把我拉到屏幕前，教我怎么用 GitLab 的 Merge Request 把每一次改动变成一次可讨论、可追踪、可回滚的"提交仪式"。

先说一个容易绕晕的点：你在搜索引擎里敲"gitlab pull request"，其实 GitLab 官方叫法是 Merge Request（MR）。GitHub 叫 Pull Request，GitLab 叫 Merge Request，本质都是"我请求把我分支上的改动合并到目标分支"，只是平台叫法不同。所以你在 GitLab 的菜单栏、文档、API 里看到的更多是 merge request。这篇文章我会把 GitLab 的 Pull Request（下文统一叫 MR）完整拆一遍：它到底解决了什么问题、一个 MR 从创建到合并要经过哪些环节、常见的报错怎么排查。内容偏实操，适合刚接触 GitLab 的团队，也适合已经在用但没系统梳理过这套流程的个人开发者。

1. 从"直接推代码"到"Pull Request"：思路转变才是核心

1.1 先澄清一个叫法：GitLab 里为什么是 Merge Request

很多新手第一次在 GitLab 上找 Pull Request，找半天找不到，后来才发现菜单上写的是 Merge Request。这个差异其实有历史原因：GitHub 的协作模型默认是"fork + pull"，我把仓库 fork 一份，改完代码，向原仓库发起一个"拉取请求"，请求对方把我的改动拉过去；GitLab 的默认模型更偏向"同一个仓库内开分支"，我改完代码，请求管理员或审核人把这个分支"合并"回主分支。两条路径殊途同归，但在 GitLab 里你只需要记住一个词：Merge Request。

搜索的时候，GitLab 自己的搜索框其实能识别 pull request 和 merge request 两种写法，但文档、API 参数、命令行提示里统一是 merge request。如果你在 GitLab 上跟同事说"发个 PR"，大家通常也能听懂，但正式流程里更标准的说法还是"提个 MR"。

1.2 MR 机制解决的三件事：代码质量、过程留痕、降低合并冲突

为什么要用 MR，而不是直接把代码推到主干？我觉得核心原因有三个。

第一，强制做代码审核。 写代码的人对自己的代码天然有盲区，逻辑漏洞、边界情况、风格问题，靠自己 review 常常发现不了。有了 MR，改动在合并之前会暴露给至少一个其他成员，别人可以在具体某一行代码上直接评论，说"这里有个并发问题"或者"这个命名看不懂"。这个过程不需要面对面，不需要开会，异步就能完成。团队里哪怕只有一个认真看代码的人，整体质量都能提升一个档次。

第二，过程留痕。 直接推代码，改了什么、为什么改，全靠提交记录猜。MR 把整个变化过程变成了一个完整档案：背景描述、代码 diff、讨论记录、CI 结果、审批人、合并时间，全部绑在一起。三个月后你回溯一个问题，打开当时的 MR，所有信息都在，不用翻聊天记录，不用问"这代码谁写的"。

第三，降低合并冲突的概率。 直接往主干推代码，多人并行开发时冲突是家常便饭。MR 机制配合"小步提交、频繁合并"，每个分支的生命周期很短，改动范围小，冲突自然少。就算有冲突，MR 界面也会提前标出来，让你在合并前解决，而不是在上线前爆发。

拿图书馆打比方：直接推代码就像所有人围着一本书同时往上写，你写一段我写一段，最后谁也看不清；MR 就像借书登记、批注审核、审批入馆，每个人都能看到你改了哪页、为什么改、谁批准了这次修改。

1.3 什么场景必须用 MR，什么场景可以不用

MR 不是银弹，不是所有项目都需要。我个人经验是这么分的：

• 需要用的场景：多人协作的正式项目；有 main、master、develop 这类公共分支的项目；开源项目；公司要求审计留痕的项目。只要团队人数超过两个，我建议至少在主干分支上开启"禁止直接推送"的保护策略，强制走 MR。
• 可以不用的场景：个人玩具项目、单分支试验项目、一次性脚本仓库、只有你自己提交代码且不需要 review 的内部工具。强行在这些项目上走 MR 反而增加负担。

如果你在纠结"到底要不要上 MR"，我的建议很直接：先给主干分支加上保护，禁止直接 push，逼自己走一次完整 MR 流程。走完之后你再决定要不要保留这套限制。多数人的结果是——回不去了。

2. 核心细节解析与实操要点：从创建分支到 MR 被合并的全过程

2.1 分支管理和命名规范：没有规范，MR 就是一团乱麻

MR 的前提是分支，分支如果乱，MR 的质量肯定高不了。我见过不少团队，分支名字千奇百怪：test1、aaa、dev、111，打开 MR 列表根本不知道这个改动是干什么的。这里推荐一套简单实用的命名思路：

命名的时候把功能点或缺陷编号带上，比如 fix/JIRA-123-login-redirect，一眼就能看出这个分支要解决什么问题。实际开发中，从 MR 列表看见清晰的 fix/xxx 分支名，比从 git log 里一层层翻提交记录高效得多。

分支的另一个关键操作是"保护分支"。在 GitLab 仓库设置里，进入 Settings → Repository → Protected Branches，把 main 或者 master 设置为保护分支，选的权限是：

• Allowed to merge：Maintainer（或按公司要求设置）
• Allowed to push：Maintainer（或者直接设为 No one）

这样普通开发者的代码就无法直接推送到主干，所有改动都必须从分支发起 MR。这是整个 MR 流程能落地的最重要一步。

2.2 创建 MR 的两种路径：网页操作与命令行推送

创建 MR 通常有两条路：一条是纯网页操作，另一条是本地推完分支后，顺着 GitLab 给你的提示链接点进去创建。我两个都用，一般场景是这样的：

网页操作路径：进入项目仓库页面，在左侧菜单点 Merge Requests，然后点 New merge request，选择源分支（你要合并过来的分支）和目标分支（你要合并进去的分支），GitLab 会先帮你比较两个分支的差异，显示"可合并"或"存在冲突"，然后填写标题、描述、审核人，点击创建。这个路径适合分支已经推送到远端的情况。

命令行推送路径：本地创建分支、改代码、提交，然后 git push 的时候，GitLab 会在终端输出一段提示，直接给你一个创建 MR 的 URL。复制到浏览器打开，就是一个已经帮你选好源分支和目标分支的创建页面，只需补标题和描述就可以提交。这个路径我推荐所有人习惯起来，因为不用切到浏览器去手选分支，减少出错。

2.3 MR 页面里的关键字段和配置项

一个 MR 页面看起来字段很多，但真正需要关注的其实就几个：

标题和描述。标题要一眼能看懂，比如"修复订单状态重复展示问题"就比"fix bug"强。描述建议包含三块：改动背景、具体改动内容、测试结果。很多团队会用 MR 描述模板，GitLab 也支持在项目里配置 .gitlab/merge_request_templates/ 下的模板，把必填项固定下来，防止有人只写一句话就提交。

审核人和指派人的区别。Assignee 是"这个 MR 由谁负责跟进"；Reviewers 是"请谁来看代码"。一个人可以既是 Assignee 又是 Reviewer，但建议 Assignee 只设一个，Reviewers 可以设多个。我之前见过 Assignee 塞了三个人，结果三个人都以为别人会处理，MR 挂了一周没人管。

Merge options。合并选项里有几个勾选项很重要：

• Delete source branch when merge request is accepted：合并后自动删除源分支，建议勾上，保持远端分支干净。
• Squash commits when merge request is accepted：把 MR 里所有提交合并成一个提交，适合功能分支提交历史比较碎的情况，但如果你希望保留每次提交的详细记录，就不要勾。

关联 issue。在描述里写 Closes #123 这样的格式，MR 合并时 GitLab 会自动关闭对应的 issue。这个功能非常实用，省去手动去 issue 页面操作的步骤。

2.4 审核、评论与 CI：让 MR 真正起到把关作用

MR 创建只是开始，真正的价值在后续的 review 和 CI 环节。GitLab 支持在 MR 的 Changes 页面对每一行代码插入评论，审核人可以直接在出问题的代码上挂一个 comment，作者看到评论后可以回复、修改代码并更新 MR。这套行内评论机制用好了，比任何代码评审工具都高效。

除了人工审核，MR 还可以绑定 CI/CD 流水线。你在 .gitlab-ci.yml 里配置好流水线之后，每次推送新的提交，GitLab 会自动触发流水线，在 MR 页面直接显示 pipeline 是 running 还是 passed。我个人的习惯是：

• MR 未通过 CI，坚决不合并；
• MR 至少要有一个人 Approve，才允许点合并按钮；
• 合并按钮我自己也会检查一遍 diff，确认没有调试代码和临时文件混进去。

这个流程里最重要的一点是 MR 要小。 一次 MR 改 10 个文件、涉及 5 个功能点，review 的人根本看不过来。把大改动拆成多个小 MR，每个 MR 只解决一件事，review 效率和质量都会明显提升。我在团队里对新人常说的就是：如果你发了一个超过 500 行变更的 MR，先停下来想想能不能拆成两个。

3. 实操过程与核心环节实现：完整跑通一次 MR

3.1 环境准备：SSH 密钥、账号配置与 Token 获取

真正开始操作前，有三样东西建议先确认：SSH 密钥、git 账号信息、Access Token。

SSH 密钥。在 GitLab 上拉代码、推代码，最方便的方式是用 SSH 协议。生成密钥的命令很简单：

bash复制ssh-keygen -t ed25519 -C "你的邮箱" -f ~/.ssh/id_ed25519

一路回车就能生成。然后把公钥加到 GitLab：

bash复制cat ~/.ssh/id_ed25519.pub

复制输出内容，登录 GitLab，打开右上角头像 → Preferences → SSH Keys，粘贴公钥，保存。之后验证一下连接：

bash复制ssh -T git@你的gitlab域名

首次连接会提示是否确认主机指纹，输入 yes 即可。看到 Welcome to GitLab, @你的用户名! 就说明配置成功了。

git 账号信息。提交代码的时候，Git 会带着 user.name 和 user.email 两个字段，这两个字段最好和 GitLab 账号保持一致。怎么检查：

bash复制git config --global user.name
git config --global user.email

如果不一致，改一下：

bash复制git config --global user.name "你的名字"
git config --global user.email "你注册GitLab的邮箱"

这一步看着简单，但很多人本地推送没问题、代码贡献统计却显示不出来，根因就是 user.email 和 GitLab 账号不一致。

Access Token。SSH 用于 git 命令行操作，而一些 IDE 插件、第三方工具调用 GitLab API 时需要用到 Access Token。创建路径：头像 → Preferences → Access Tokens，点 Add new token，填写名称、设置过期时间、勾选权限范围。常用的权限范围有：

这里提醒一句：token 只会在创建时完整显示一次，刷新页面后就再也看不到了，一定要复制保存好。旧版本 GitLab 和老 token 如果权限设置不完整，会导致 IDE 插件直接报错，下面第 4 节我会专门说这个问题。

3.2 从本地新分支到推送远端：一个最小可用示例

环境准备妥当之后，完整的操作流程其实很简单。假设我要修一个登录页跳转的 bug，我通常这样操作：

bash复制# 先切回目标分支，拉取最新代码，避免在旧代码上开分支
git checkout main
git pull origin main

# 创建新分支
git checkout -b fix/login-redirect

# 修改代码，可以看下改动范围
git diff

# 提交
git add .
git commit -m "fix: 登录后跳转地址错误，修正回跳参数"

# 推送新分支到远端
git push -u origin fix/login-redirect

推送完成之后，注意终端输出。GitLab 会给你一个 remote 提示，内容类似：

text复制remote:
remote: View merge request for fix/login-redirect:
remote:   http://你的gitlab域名/yourgroup/yourproject/-/merge_requests/new?merge_request%5Bsource_branch%5D=fix/login-redirect
remote:

直接在浏览器里打开这个链接，就会进入创建 MR 的预填页面，源分支已经选好，只需要补标题、描述和审核人。如果你用的是 HTTPS 协议拉代码，推送时还需要输入用户名和 token（密码框粘贴 token 即可）。

3.3 在网页上发起 MR 并配置审核人

打开创建 MR 的页面之后，你会看到几个关键区域：

源分支和目标分支。源分支是你刚才推送的 fix/login-redirect，目标分支是 main。确保目标分支选对了，我见过有人把目标分支选成另一个功能分支，结果 MR 合并到了错误的地方。

标题和描述。标题我习惯按"类型: 一句话说明"的格式写，比如 fix: 登录后跳转地址错误。描述部分如果是团队有模板就按模板填，没有模板的话，我会写三块内容：背景（这个 bug 是怎么发现的，影响范围是什么）、改动说明（改了哪些文件、为什么这样改）、测试情况（本地怎么验证的，结果如何）。一个好记的口诀是"背景-改动-验证"三条。

Reviewers 和 Assignee。Reviewers 填上你认为应该看代码的同事，Assignee 填你自己（如果你是这次变更的负责人）。如果团队里配置了 Code Owner 规则，GitLab 会自动在代码 diff 里标注需要哪些人审批，这个功能对敏感目录的保护很管用。

都填好之后，点 Create merge request。MR 就生成了。

3.4 处理评论、更新分支与合并策略选择

MR 创建之后，审核人可能会在代码行上留下评论。这时候你的操作流程是：本地修改代码 → commit → push。推送之后 MR 会自动更新，不需要重新创建，也不需要额外操作。

如果是几个 commit 之间的逻辑比较乱，或者审核人建议把提交历史整理一下，可以先 rebase 再强制推送：

bash复制git fetch origin
git rebase origin/main
git push --force-with-lease

这里一定要用 --force-with-lease，不要用裸的 --force。前者会检查远端是否有别人推了新提交，如果有就拒绝强制推送，避免覆盖同事的代码；后者是无条件覆盖，很容易把别人刚推的提交冲掉。这是我见过新手犯的最危险错误之一。

MR 审核通过、CI 也通过之后，就到了合并环节。GitLab 里常见的合并策略有四种，区别如下：

多数团队默认用 Merge Commit，因为它最安全，信息保留最全。我自己做开源项目时倾向于 Rebase Merge，让主分支历史保持一条直线，配合"一个 MR 一个功能"的习惯，回滚和定位问题都更省事。合并之前，我把 Delete source branch 勾上，合并后远端分支自动清掉，本地分支自己手动清理：

bash复制git branch -d fix/login-redirect

注意这里是小写的 -d，它会先检查分支是否已经被合并，如果没合并会拒绝删除，起到一层保护作用。如果想强制删，才用 -D。

4. 常见问题与排查技巧实录

4.1 登录失败：Check API Token or GitLab Version

不少人在 VSCode 的 GitLab 插件、GitLab Runner 配置或者其他 IDE 集成工具里遇到过这个报错：

login failed. check api token or gitlab version. log in via git if the version is old.

这个提示直译过来就是"登录失败，检查 API Token 或 GitLab 版本"。我排查这个问题一般按顺序走三步。

第一步，确认 token 本身是不是有效的。 打开 GitLab，头像 → Preferences → Access Tokens，看看有没有和插件里填的一致的 token，token 是否过期、是否被 revoke。如果 token 是新生成的，确认权限 scope 里勾了 api 或者至少 read_api。很多插件只读操作也需要 api scope，不是 read_user 就够的。

第二步，确认 token 是否填对。 有些工具不止填 token 一个字段，还要填 GitLab 的 API 地址。比如 GitLab 的 API 路径通常是 https://你的gitlab域名/api/v4/，不带 v4 会导致部分功能拿不到数据。公司内网部署的 GitLab 如果走了子路径，比如 https://git.example.com/gitlab，API 地址也要对应加上子路径。

第三步，确认 GitLab 版本与插件兼容性。 新版本插件调用的 API 接口，在老版本 GitLab 上可能不存在，或者行为不一样。如果插件能设置 GitLab 版本，把它往低调一档试试；如果插件不提供版本设置，又确认 API 地址和 token 都没问题，那就只能换用兼容老版本的插件，或者升级 GitLab。

这个报错在团队混合使用新旧 GitLab 实例时尤其常见，一个实例上 token 没问题，换到另一个实例就报错，基本都是版本兼容问题。

4.2 GitLab 422 登录错误与隐身模式

网页端登录 GitLab 时偶尔会遇到 422 Unprocessable Entity 的错误，这个错误码在浏览器里出现很迷惑，因为它不是 500（服务器内部错误），也不像 401/403（认证授权问题），而是"请求格式或校验不过"。

我遇到 422 比较多的场景有两个：一个是登录提交的时候报，另一个是创建 MR 或者编辑 issue 点保存时报。先说结论：90% 的情况下，422 跟浏览器缓存和 Cookie 有关，尤其是 CSRF token 校验失败。GitLab 的登录表单和操作请求都会带一个 CSRF token 做校验，如果你的浏览器缓存了旧的 Cookie 或 token，而服务端已经换了新的，就会 422。

排查和解决办法，按效率排序：

1. 先开隐身模式试一下。隐身模式不会带旧的 Cookie 和扩展的干扰，如果隐身模式下能正常登录，基本可以断定是浏览器本地的状态问题。这一步我几乎是必做的，因为成本最低。
2. 清掉 gitlab 域名下的 Cookie。浏览器设置里找到该站点的 Cookie 清理掉，重新登录。
3. 停用浏览器插件再试。有一些翻译插件、去广告插件、脚本管理插件会修改页面上的表单内容，干扰 CSRF token。我遇到过的是某个翻译插件自动翻译页面，把隐藏的 token 字段也动了，导致提交必 422。
4. 换个浏览器。如果以上都不行，换 Chrome/Firefox/Edge 交叉验证，能区分到底是浏览器环境问题还是 GitLab 服务端问题。

如果所有浏览器都是 422，那就要怀疑是不是 GitLab 服务端的时间不对或者 session 存储有问题。公司内网部署的 GitLab 如果跑在容器里，容器时间不同步会导致 session 校验异常，需要运维检查服务器时间同步。

4.3 推送被拒：账号不一致与权限不足

推送分支的时候被拒绝，最典型的是 403 或者 You are not allowed to push code to protected branches。前者是权限不足，后者明确告诉你目标分支被保护了。

先说保护分支的问题。如果 main 分支被设为保护，普通开发者直接 git push origin main 就会报错。解决办法不是绕过保护，而是按流程来：

bash复制git checkout -b fix/xxx
git push -u origin fix/xxx

然后去 GitLab 创建 MR，走审核合并流程。如果你们团队保护分支允许特定角色推送，那要确认你的账号在项目里的角色是不是够——比如 GitLab 项目角色分 Guest、Reporter、Developer、Maintainer、Owner，默认情况下 Developer 不能推保护分支，Maintainer 以上才可以。

再说账号不一致的问题。这个坑比较隐蔽：本地 git 的 user.name 和 user.email 配置成什么样，commit 提交记录里就会带什么样。很多人电脑上配过多个 git 账号，某个仓库里残留了旧邮箱，提交记录里的 author 邮箱跟 GitLab 账号对不上，GitLab 就不认为这个提交属于你。表现就是：代码推上去了、MR 也建了，但提交记录里的头像和名字是灰的，甚至权限校验出错。

解决办法是统一配置：

bash复制git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
git config --global --list | grep user

如果已经有历史提交使用了错误身份，可以针对这个仓库单独修正最近几条提交的 author 信息。不过我要提醒一句：修改已推送提交的作者信息属于重写历史，如果你已经 push 过的分支被别人拉取了，尽量不要改，或者改完用 --force-with-lease 推送并通知团队。最稳妥的方案还是从源头保证新的提交是对的。

4.4 合并分支时的冲突与回滚

MR 创建之后，GitLab 会显示"可自动合并"或"存在冲突"。如果显示冲突，基本是目标分支上有别的合并先改了你这块代码。

简单的冲突可以直接在 GitLab 网页上解决：MR 页面往下拉，如果 GitLab 判定冲突可以安全合并，它会显示一个 Resolve conflicts 的按钮，点进去在网页编辑器里逐行选择保留哪边的代码。这个功能我实测对单行变更比较友好，但遇到大段重构，网页编辑器反而很痛苦，不如本地解决。

本地解决冲突的推荐流程：

bash复制# 先更新本地目标分支
git fetch origin
git checkout main
git pull origin main

# 切回功能分支
git checkout fix/login-redirect
git merge origin/main
# 或者 git rebase origin/main

merge 和 rebase 各有优劣：merge 会产生一个新的合并提交，历史会有分叉，但冲突只需要解决一次；rebase 历史是线性的，但冲突可能需要反复解决。我个人在功能性分支上习惯用 git merge origin/main，在需要保持线性历史的场景才用 rebase。

无论用哪种方式，冲突解决完之后都要重新跑一遍测试再推送。推送后用 --force-with-lease 更新 MR。

回滚的场景也值得说。MR 合并之后发现写坏了，首先要判断：这个分支是不是已经影响线上？ 如果是刚刚合并、影响还在 MR 阶段，最简单的办法是在合并页面点 Revert，GitLab 会自动创建一个反向 MR。如果是已经上线之后发现有问题，按紧急程度处理，线上服务直接挂掉的话就先用版本回滚。

这里要特意强调一个很多人都踩过的坑：不要对公共分支执行 git reset --hard 然后强制推送来"撤销合并"。reset 是删掉历史，公共分支上其他人已经基于这个历史拉过代码了，你一 reset 再 force push，其他人的本地仓库会全线爆掉。正确的公共分支回滚姿势是用 git revert，它会新增一个提交来抵消之前的改动，历史不会被重写，大家同步也友好。

4.5 无法统计推送代码量

团队考核看代码量时，经常有人说"我明明提交了，为什么统计不到我的推送量"。这个问题在 GitLab 上常见原因有三个。

第一个是邮箱不一致。前面已经说过，提交里的 author 邮箱和 GitLab 账号邮箱对不上，这条提交就会被当成匿名或不存在的人。GitLab 的贡献统计是按提交关联的邮箱来归因的，解决方式是把 git config 的 user.email 改成注册 GitLab 用的邮箱，已经产生的历史提交要用 git filter-branch 或 filter-repo 改写，操作有风险，务必谨慎。

第二个是统计工具只看合并到特定分支的提交。很多报表脚本统计的是 main 分支上的提交，而你在 MR 合并时选了 Squash Commit，一条 MR 压成了一个提交，作者变成了发起 MR 的人。如果发起 MR 的人和实际开发者不是同一个账号，squash 之后代码量可能记到发起人头上。想避免这个情况，要么不勾 squash，要么让实际开发者自己发起 MR。

第三个是分支长期不合并。代码写到分支上，但 MR 迟迟不合并，统计自然看不到。这种情况不是统计问题，是流程问题——小步提交、频繁合并的价值就在这里。

最后分享一个我自己的使用习惯。用了几年 GitLab MR 之后，我最大的体会是：MR 的价值不在于流程本身，而在于它逼着我们把一次改动说清楚。哪怕你现在是独立开发一个人写项目，把每次都提交成 MR，以后翻记录、回溯问题、写周报，都比直接 commit 要轻松太多。

再补充一个小技巧：在 MR 描述里用 Closes #123 这样的写法，合并时 GitLab 会自动关闭对应的 issue，省去手动去 issue 页面操作的一步。如果是团队协作的项目，还可以在 MR 里用 /assign @username 这类 quick action，提交时一键指派审核人，效率能提升不少。流程这种东西，刚开始觉得繁琐，等养成习惯之后，你会发现自己已经离不开它了。