Git分支策略与Code Review流水线：支撑百人研发团队的协作体系

一、问题背景：从“能跑”到“跑不稳”的协作阵痛

2022年Q3，我们团队因业务扩张，从20人迅速增长到120人，前端仓库从单仓变成了10+个微前端子应用。起初大家很随意，直接在develop分支上提交，偶尔拉个feature分支，但很快问题集中爆发：

1. 合并地狱：每周五的合并大会，光解决冲突就要花掉半天，develop分支长期处于“红码”状态。
2. Code Review形同虚设：因为大家共用一个长分支，为了赶进度，很多MR都是“先合后补”，评审变成了走流程。
3. 发布失控：没有清晰的release分支，导致每次发版都不知道线上到底包含了哪些commit，回滚成本极高。

那一刻我意识到，问题不在代码能力，而在于Git工作流没有跟上团队规模的增长。我们需要一套明确的规则，让机器去执行规则，把人从冲突和扯皮中解放出来。

二、环境与版本：我们选择的技术栈基线

在制定方案前，我们先锁定了工具链版本，避免因环境差异导致流程失效：

• Git版本：2.39.1（强制要求团队升级，使用git worktree和更快的合并算法）
• GitLab版本：15.11.3（社区版，支持原生CI/CD和Merge Request规则）
• Node.js：18.16.0（用于前端项目）
• 包管理器：pnpm 8.6.0（为了配合CI缓存优化）

三、方案设计：混合分支策略（Trunk-Based + GitFlow 混搭）

我们最终没有照搬任何一种模式，而是结合业务特点设计了“主干开发 + 短生命周期特性分支 + 独立发布分支”的混合模型。

核心规则如下：

1. 主干分支 main：唯一可发布的分支。永远保持绿色，禁止直接push，只能通过Merge Request合入。
2. 开发分支 dev：日常集成分支，所有feat分支合入这里。每当main有更新，必须立即同步回dev。
3. 特性分支 feat/xxx-功能描述：从dev拉出，生命周期不超过3天。超过3天必须拆分子任务。
4. 发布分支 release/x.y.z：从main拉出，只接受bug修复类提交（fix/），同时进行版本号递增。
5. 热修复分支 hotfix/xxx：从main拉出，修复后同时合回main和dev。

为什么不用纯GitFlow？ 因为GitFlow的develop和release长期并行，对百人研发团队来说太容易产生漂移。为什么不用纯Trunk-Based？ 因为我们的业务版本节奏固定（每两周一个版本），需要release分支来隔离发布期的不稳定代码。

四、核心实现：Code Review 流程与 CI/CD 集成

4.1 强制Code Review的MR模板

我们通过GitLab的Merge Request模板来约束信息完整度。在项目根目录创建.gitlab/merge_request_templates/Default.md：

## MR描述

**关联Issue**：`#123`（必填，否则CI直接失败）
**变更类型**：`feat` / `fix` / `refactor` / `docs`（选一）
**影响范围**：如涉及微前端子应用，请标注子应用名称

## 自测清单
- [ ] 本地已通过 `pnpm lint` 且无Error
- [ ] 本地已通过 `pnpm test` 且覆盖率不低于80%
- [ ] 已运行 `pnpm build` 确认无类型错误

## 测试说明
- 请描述如何验证此变更：____________________

## 截图（UI变更必填）
- Before/After截图：

---

## 评审人注意事项
- 请重点检查：错误边界处理、API调用失败兜底、是否引入循环依赖。

4.2 GitLab CI 自动化门禁（.gitlab-ci.yml 核心片段）

为了让“强制Code Review”不流于形式，我们在CI流水线中加入了自动化门禁。以下是一个真实可用的配置片段，基于GitLab 15.11的rules语法：

# .gitlab-ci.yml (核心片段)
stages:
  - lint
  - test
  - build

cache:
  key: "$CI_COMMIT_REF_SLUG"
  paths:
    - node_modules/
    - .pnpm-store/

variables:
  PNPM_CACHE_FOLDER: ".pnpm-store"

before_script:
  - corepack enable
  - corepack prepare pnpm@8.6.0 --activate

lint-job:
  stage: lint
  image: node:18.16.0
  script:
    - pnpm install --frozen-lockfile
    - pnpm lint -- --max-warnings=0  # 任何warning都视为失败
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "dev"'

test-job:
  stage: test
  image: node:18.16.0
  script:
    - pnpm install --frozen-lockfile
    - pnpm test -- --coverage --coverageReporters=json-summary
  coverage: '/All files\s*\|\s*([\d\.]+)/'
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      allow_failure: false  # 强制要求通过

build-job:
  stage: build
  image: node:18.16.0
  script:
    - pnpm install --frozen-lockfile
    - pnpm build
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: always
    - if: '$CI_COMMIT_BRANCH == "dev"'
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

关键配置说明：
- --max-warnings=0：这个参数极其重要，它让ESLint不再只拦截Error，而是连Warning都不放过。我们用了两周时间把存量Warning清零，从此代码风格高度统一。
- rules条件：我们让lint和test仅在MR事件或dev分支运行时执行，避免对main的直推造成浪费（实际上main也禁止直推）。
- coverage正则：GitLab可以解析Jest输出的覆盖率文本，直接显示在MR界面，低于80%时无法合并（通过MR规则设置）。

4.3 MR合并规则（GitLab 15.11 设置）

在GitLab项目的Settings → Repository → Merge Requests中，我们启用了以下规则：

1. Pipelines must succeed：勾选，且要求最新的一条流水线必须通过。
2. All conversations must be resolved：强制解决评论对话。
3. All threads must be resolved：同上，防止“已解决”但未点击确认。
4. Allow only fast-forward merges：这是最关键的一步！ 我们弃用了--no-ff合并，强制使用Fast-forward。这意味着MR合入前必须先rebase目标分支，确保main分支是一条完美的线性历史，极大简化了git bisect排查问题的难度。

为了配合Fast-forward，我们要求开发者在合入前执行：

# 本地切换至特性分支
git checkout feat/user-login
# 拉取最新的dev分支并rebase
git fetch origin dev
git rebase origin/dev
# 强制推送（因为rebase会改写历史，需要force-with-lease）
git push --force-with-lease origin feat/user-login

五、踩坑与优化：那些文档没告诉你的细节

坑1：pnpm缓存导致CI偶尔失败
- 现象：CI中pnpm install偶发报错，提示“Cannot find module”。
- 排查：发现是pnpm的硬链接在CI容器中因路径不一致导致缓存失效。
- 解决：在cache中加入了.pnpm-store/路径，并设置PNPM_CACHE_FOLDER环境变量。注意必须使用--frozen-lockfile，防止由于lockfile更新产生不可复现的依赖。

坑2：Fast-forward合并与“陈旧MR”死循环
- 现象：开发者在MR合入前rebase了dev，但测试期间dev又前进了，导致MR总是显示“合并冲突”。
- 解决：我们写了一个自动rebase脚本（npm run rebase），内部执行git fetch origin dev && git rebase origin/dev。同时教育团队，MR的生命周期尽量控制在1天内。对于超过1天的MR，我们通过GitLab的/rebase命令让机器人自动处理。

坑3：Release分支的Hotfix回灌
- 现象：发布后发现紧急bug，直接在release/1.2.0上修复，但忘记合回dev，导致下个版本代码丢失修复。
- 解决：我们在release分支的MR模板中强制添加“必须同时合回dev”的清单项，并且在CI中增加了一个脚本检查：如果MR目标是release/*，则必须包含fix/前缀，且描述中必须有“同步至dev”的勾选。

六、效果数据：这套流程到底改变了什么？

在推行这套体系三个月后（2023年1月至4月），我们对比了关键指标：

七、总结：流程是工具，不是枷锁

这套Git工作流并非一成不变，它基于我们团队的痛点而演化。核心思想是：让CI强制校验规则，让MR模板引导沟通，让分支策略匹配发布节奏。

如果你所在团队正面临类似的规模扩张，建议不要直接照搬我的配置，而是先花一周时间调研三个问题：
1. 你们的发布节奏是持续的还是周期性的？
2. 你们的Code Review文化是“互助”还是“完成任务”？
3. 你们能否接受强制Fast-forward合并带来的rebase习惯？

如果这三点都想清楚了，这套配置可以作为很好的参考起点。最后，记住版本控制不是用来限制开发者的，而是用来保护开发者的——保护他们免受自己和他人的错误影响。希望这篇实践能对你有所启发。