企业官网建设流程全解析

做迭代做到第八天，测试同学丢过来一个问题单：某个列表页在特定机型上白屏，问是哪次改动引入的。开发同学翻本地记录翻了二十分钟，最后靠"感觉"定位到三天前的一次提交，回滚验证又花掉半天——这种场景我见过太多次，问题从来不在某个人的水平，而在于团队没有一条从"需求"到"代码"到"产物"的可追溯链路。

这篇聊的GitLib，就是我们内部对那套代码托管与协作平台的叫法，它把版本库、合并请求、评审规则、流水线串在了一个地方。配套的Scrum敏捷模式，则是我们跑了两年的迭代节奏。单独看这两个东西都不新鲜，难的是把它们接起来——让每一次提交都能回答"它服务哪个需求"，让每一个需求都能回答"它落在哪几行代码、跑过哪些检查"。这篇内容适合正在用 Git 类工具做多人协作、又觉得流程越来越乱的团队看，尤其是刚开始规范化的中小团队；也适合刚接手仓库管理职责的同学，当成一份上手清单来读。下面我按"它有什么能力—哪些能力真正值得配—怎么套进迭代—怎么落地—哪里容易翻车"这个顺序讲，全部是我们自己踩过一遍的东西。

1. GitLib 这套工具箱里究竟装了什么

1.1 从"能存代码"到"能管流程"的三层能力

很多人第一次接触这类平台，认知停留在"一个放代码的远程地址"，clone、push、pull 三部曲走完就以为到头了。其实按能力层次拆，它至少有三层，而且价值是逐层递增的。

最底层是版本库托管。这一层解决的是物理问题：代码放在哪里、谁能读谁能写、磁盘满了怎么办、误删了怎么恢复。Git 本身是分布式的，每个人本地都有一份完整历史，但这不意味着不需要中心仓库——中心仓库承担的是"事实基准"的角色，所有人的提交最终要在一个地方对齐。这一层的能力包括仓库创建、成员与权限分组、分支列表、提交历史浏览、文件级历史追溯、标签管理。听起来平淡，但权限分组这块做不好，后面全是隐患：我见过把整个研发组塞进一个"开发者"角色里的仓库，结果任何人都有权限删分支、强推主干，出事只是时间问题。

中间层是协作层，这也是很多人低估的一层。它包含合并请求（不同平台叫法不一样，本质是"我要把 A 分支合进 B 分支，请审"）、行内评论、评审人指派、审批规则、讨论串、任务与需求的挂接、里程碑。这一层解决的是"多人同时改一份代码，怎么保证不出乱子、出了乱子能说清谁拍的板"。没有这层，代码评审就只能靠"你发我一份 diff 我看一下"，看完的结论散落在聊天记录里，两周后谁也找不到当初为什么这么改。

最上层是自动化层。提交触发流水线、跑静态检查、跑单元测试、构建产物、打标签、推到制品库、触发部署。这一层解决的是"人不可靠"这个朴素事实——再细的规范文档，也比不上一条自动执行的检查。

这三层的关系不是并列的，是递进的。托管层没理顺，协作层就是一锅粥；协作层没规矩，自动化层跑出来的绿灯也没有意义，因为没人知道这个绿灯代表谁的需求通过了。

1.2 和"裸用 Git"的边界到底在哪里

这里要说清楚一件事：GitLib 不是 Git 的替代品，它在 Git 之上加了一层策略。Git 本身只管内容寻址和提交图的正确性，它不关心"谁有资格往主干推"、"合并前有没有人审过"、"审完有没有跑测试"。这些全是平台层的事。

我做过一个对照表，帮新同事理解边界：

看得出来的结论是：Git 保证"不会丢"，GitLib 保证"不会乱"。一个团队如果只有三五个人、一周发一次版、彼此坐在一起，裸用 Git 加口头约定也能活；但只要人数过八、迭代周期缩到两周、有人在异地，口头约定立刻失效，因为信息传递的带宽不够了。

顺带说一句常见的误解：有人觉得用了平台就等于敏捷了。完全不是一回事。平台只是把流程固化的工具，流程本身设计得烂，固化下来只会更烂——比如要求每个合并请求必须有三个审批人，在五人团队里就是纯阻塞。

2. 分支保护、合并请求与流水线：三样最该先配好的东西

平台功能列表能拉很长，但按投入产出比排，前期真正值得花时间配的只有三样。这三样配好，剩下的大部分功能都是锦上添花。

2.1 分支保护规则：把"谁能动主干"写死在配置里

主干分支（我们叫 main，有的团队叫 master 或 trunk）是所有分支的公共祖先。它的特殊性在于：一旦历史被改写，所有基于它的分支都会错位，恢复成本极高。所以这条规则必须是硬约束，不能靠自觉。

保护规则里我建议至少打开这几项：

• 禁止直接推送，所有变更必须走合并请求。这一条断掉的是"我改一行小东西直接推上去"的路径。听着烦，但它强制了变更被看见。
• 禁止强制推送。强推在个人分支上是效率工具，在主干上是灾难按钮。
• 最少审批人数。五人以下团队设 1 人，十人以上设 2 人，不要设 3 人——三个人凑齐的时间成本会让流程彻底堵死。
• 流水线必须通过。这是把"测试跑过了"从口头承诺变成准入条件。
• 合并前分支必须是最新的。这条防止的是"我基于三天前的主干开发，合并时把别人刚修好的东西覆盖回去"。
• 新成员第一周只给特性分支写权限。这是我个人的保守做法，新人熟悉仓库结构和规范之后再放开，比出事后追责体面得多。

配这些的时候有个心态问题要摆正：规则是给未来的自己设的护栏，不是给现在的人设的门槛。我第一次配的时候也觉得"这么严会拖慢节奏"，实际跑了一个迭代后发现，慢的那部分时间全都花在了本该被拦下的问题上，等于把返工提前了，总时长反而短。

2.2 合并请求：让评审意见真正能落地

合并请求这个机制，价值不在于"能发起一次评审"，而在于评审过程本身被结构化了。它把散落在聊天里的意见变成挂在具体代码行上的评论，把"我觉得这样不好"变成"第 47 行这里，空指针没判"。

我见过效果最差的用法，是把合并请求当成一个通知：发起来，@ 一下同事，同事回个"OK"，合并。这种用法下，合并请求只是个仪式。真正有产出的用法需要几个配置配合：

第一是模板。在仓库里放一个请求描述模板，强制填写三项：这个改动解决了什么问题、影响哪些模块、怎么验证的。模板不需要很长，但"怎么验证的"这一栏特别有用——它逼着提交者想一遍自测路径，经常在这一步就自己发现遗漏。

第二是评论解决机制。评论提出后，必须由提出者或修改者标记为"已解决"才能合并。这个机制的核心作用是防止意见积压——没有它，评审人提了五条，作者改了两条就合了，剩下三条永远沉底。

第三是合并方式的选择。这里我踩过坑，展开说。常见的合并方式有三种：

我们最终选了压缩合并为主，快进为辅。理由很实在：主干历史是给未来的人看的，未来的人关心的是"哪个需求引入了这个改动"，而不是"开发过程中我提交了十七次 fix typo"。压缩合并让主干保持"一个需求一个提交"，出问题时按需回滚，粒度刚好。

代价是分支内的历史被抹掉了。所以我的做法是在合并请求描述里附上分支内的提交列表，作为补偿记录，两者结合，追溯信息不丢。

2.3 流水线：把"我本地跑过了"变成"机器跑过了"

流水线这块最常见的失败模式不是配不起来，是配得太慢。第一次反馈时间超过十分钟，开发者就会开始绕过它——先合并，回头再看，然后就没有回头了。

我的建议是分阶段接入，第一阶段只做三件事，控制在三分钟内：

1. 静态检查。代码风格、明显的语法问题、依赖引入的许可证扫描。
2. 单元测试。只跑本次改动涉及的模块，或者用缓存跳过未变更部分。
3. 构建产物。编译一遍，确保能打包。

第二阶段再加集成测试、覆盖率门槛、镜像构建这些耗时环节。这个顺序不能反——先把"必经之路"跑顺，再加负担。

还有一个容易被忽略的细节：提交前的本地检查。服务端流水线再快也是分钟级，本地钩子能做到秒级。我们把格式化检查和提交信息规范校验放在本地钩子里，格式不对根本提交不上去。这一步拦掉了大概六成会在流水线上失败的低级问题。

提示：本地钩子是可以被跳过的，所以它只能算"体验优化"，不能算"质量保障"。真正的准入门槛必须放在服务端。

3. 把 Scrum 的三类工件挂到代码上

Scrum 本身有一套自己的语言：产品待办列表、迭代待办列表、增量。听着抽象，落到 GitLib 上其实就是三个问题——需求怎么挂到分支上，站会看什么数据，评审和回顾的证据从哪来。

3.1 需求条目、任务卡片与提交的关联方式

关联的本质是一个编号贯通的设计。我们约定：每个需求在任务看板里有一个唯一编号，编号会依次出现在四个地方：

• 分支名：feature/REQ-384-order-export
• 提交信息：feat(order): REQ-384 支持按时间范围导出
• 合并请求标题：REQ-384 订单导出支持时间范围筛选
• 制品标签：req-384-v1.2.0

这样一来的效果是：从需求编号出发，能一路查到分支、每条提交、评审意见、流水线结果、最终产物版本；反过来从任意一条提交出发，也能反查到它服务的是哪个需求、当时是怎么评审的。

这套机制听起来笨，但它解决的是一个非常具体的痛点——"这个改动为什么这么写"这个问题，三个月后基本没人答得上来。有了关联，答案就在合并请求的讨论串里。

实操层面有个细节值得注意：编号不要手工敲，容易错。我们用了一个提交信息模板，git commit时自动弹出，编号从分支名里提取预填，开发者只需要写描述。降低摩擦，规范才活得住。

3.2 每日站会该看哪几块数据

站会的本意是同步进度和暴露阻塞，但实际执行中很容易变成"流水账汇报"。我的做法是在站会前两分钟，把几块数据投在屏幕上，让讨论有锚点：

• 昨天合并了几个请求，以及当前待评审的请求数和最老的停留时长。后者是关键指标，如果有一个请求挂了三天没人看，说明评审资源是瓶颈，当天就得处理。
• 流水线失败率。如果连续多条失败，往往不是代码问题，是环境或依赖出了问题，需要立刻查。
• 进行中的卡片对应的分支状态。有没有分支超过五天没动过？有的话要么是占用资源，要么是遇到阻塞没说出来。

这里必须强调一句：这些数据是用来暴露流程瓶颈的，绝不能用来考核个人。一旦和绩效挂钩，数据立刻失真——大家会开始追数字而不是追问题，然后所有指标同时变得好看且毫无意义。这条我吃过亏，后面会细说。

3.3 评审会与回顾会的证据从哪来

迭代评审会要演示的是"增量"，也就是这次迭代真正可用的东西。经常出现的尴尬是：演示环境跑的和代码里的不一致，讲了半天发现演示的是上一版。有了制品标签就不存在这个问题——演示前确认当前制品标签对应的提交哈希，与主干最新一致，讲的就是这次的东西。

回顾会更容易流于形式，因为大家回忆的都是印象最深的事，而不是真实发生的事。我们改成从数据出发，看几个东西：

• 合并请求从发起到合并的平均时长，以及最长的三个。挑那三个出来复盘，往往能挖出具体问题，比如某次是因为接口约定变更没同步导致来回改了五轮。
• 冲突热点文件。统计这个迭代里冲突最频繁的文件，通常是架构耦合点或者多人抢改的地方，这是重构的强信号。
• 返工次数。一个需求合并后又被回滚或者追加修复，标记出来看原因。

这些数据都不需要额外工具，平台本身的历史记录里就有，导出整理一下即可。

4. 迭代节奏下的分支策略怎么取舍

分支策略是这类平台用得好不好的分水岭。策略选错，后面所有规则都在跟人对抗。

4.1 三种分支模型的对照与我的选择

先把三种主流模型摆出来：

我们一开始照搬了第三种，理由是"看起来最规范"。结果第一个迭代就出问题：一个紧急缺陷要修，得从主干修完合到开发、再合到预发，三次合并三次冲突，修一个两行的问题花了一下午。

后来换成第二种，也就是主干保持随时可发布，需求走特性分支，发布前切一个发布候选分支。具体流程是：

1. 从主干切feature/REQ-xxx，开发期间每天把主干合进来一次，保持同步。
2. 开发完成发起合并请求，压缩合并进主干。
3. 迭代结束前从主干切release/迭代号，只允许修缺陷，不再加需求。
4. 发布验证通过，打标签，主干继续往前走。

这个模型的好处是只有一条长期分支，冲突面小；坏处是主干必须真的随时可发布，这就要求流水线必须靠谱。所以第二节里说流水线要最先配，它是这个模型的地基。

有一个细节很多人忽略：每天把主干合进特性分支，而不是反过来。前者是特性分支追主干，冲突在分支内解决，影响面只在自己；后者是主干被分支污染，一旦出问题影响所有人。这个方向不能搞反。

4.2 迭代中途插单怎么处理

这是敏捷落地绕不开的现实问题：迭代跑到一半，业务方提了个"很急"的需求。处理方式直接决定了迭代能不能守住。

我们的规则是分档：

• 线上故障类：立刻处理，从主干切热修分支，走快速通道（审批人减为一人，但仍需流水线通过），修完直接合主干并回合并到当前发布候选分支。
• 半天以内的小改动：允许插单，但必须在看板上单独标记，迭代结束统计插单占比。
• 超过半天的新需求：不插，进下一个迭代的待办列表，由产品负责人对外沟通。

关键在第三条的执行力。我见过太多团队在这一步软下来，"就这一次"变成每次都有，然后迭代承诺彻底失效，团队开始不相信计划，敏捷就退化成了"两周一次的小瀑布"。

统计插单占比这个动作很重要，它是给管理层看的客观数据。当这个数字超过 30%，说明不是团队执行力问题，是计划机制本身有问题，需要往上调整，而不是继续压团队。

5. 从零跑通一条"提交即关联"的最小链路

前面讲的都是设计和取舍，这一节给能直接抄的步骤。目标是用半天时间，把一个仓库从"裸的"变成"有规矩的"。

5.1 仓库初始化与目录约定

新建仓库后先别急着推代码，把几个基础文件放进去，这些文件是后续所有规范的地基：

/ ├── README.md 项目说明、本地启动方式、分支模型说明 ├── .gitlib/ │ ├── merge_request_templates/default.md │ └── CODEOWNERS 路径归属声明，指定谁必须审哪些目录 ├── .gitlib-ci.yml 流水线配置 └── docs/ └── branch-strategy.md 分支模型与命名约定，给新人看

CODEOWNERS这个文件值得单独说。它按路径声明归属，比如src/payment/归支付组审，src/core/归架构组审。配好之后，改动对应目录的合并请求会自动把对应的人加进评审列表，不用手动 @。这个东西的价值在于：它把"该找谁审"从人脑记忆变成了配置，新人不用问就知道该找谁。

合并请求模板不用写长，四行足够：

### 关联需求 REQ- ### 改动说明 （这个改动解决了什么问题） ### 影响范围 （涉及哪些模块、有没有接口变更、需不需要数据迁移） ### 验证方式 （怎么自测的、需要回归哪些路径）

5.2 提交信息规范怎么写才不流于形式

提交信息规范最容易沦为形式主义，因为它经常被定成"必须符合某某格式"，但没人说清格式为什么长这样。我的理解是：一条好的提交信息要能被三种人读懂——三个月后的自己、接手这块的同事、以及将来要定位问题的排查者。

格式上我们用的是类型加范围的约定：

feat(order): REQ-384 导出支持时间范围筛选 原来的导出只支持全量，数据量大的时候接口超时。 这次加了起止时间两个参数，走索引查询，同时保留不传参的全量导出以兼容旧调用方。 影响：导出接口签名变更，旧调用方无需改动（参数可选）。

三个部分：首行是摘要，不超过五十字，说明做了什么；中间是动机，说明为什么做，这是最有价值的部分，也是大多数人省略的部分；末尾是影响，说明对调用方有什么变化。

关于类型前缀，不用搞太复杂，五个够用：feat（新功能）、fix（缺陷修复）、refactor（重构，行为不变）、docs（文档）、chore（构建、依赖这类杂活）。类型的作用不只是好看，它让我们能在发版时自动生成变更日志，按类型分组。

落实手段是本地钩子。我们用一个简单的脚本，在提交时校验首行格式，不符合直接拒绝，并给出正确示例。上线第一周被吐槽得厉害，两周后大家就习惯了，反而觉得省事——因为不用再想"这次该写什么"。

5.3 最小可用的流水线配置

流水线配置文件放在仓库根目录，文件名这里用.gitlib-ci.yml代指。第一版只做三件事，重点是快：

stages: - check - test - build variables: CACHE_KEY: "deps-v1" check: stage: check script: - run-lint --changed-only - run-commit-msg-check rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' test: stage: test script: - restore-cache $CACHE_KEY - run-unit-test --changed-modules cache: key: $CACHE_KEY paths: - .deps/ rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' build: stage: build script: - run-build --tag "req-${REQ_ID}" artifacts: paths: - dist/ rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

几个配置点解释一下为什么这么写：

--changed-only和--changed-modules是为了压时间。全量跑一遍要八分钟，只跑改动相关的一分半，返回时间差了五倍，直接影响开发者愿不愿意等。

CACHE_KEY缓存依赖目录，避免每次都重新拉依赖。这是最容易被忽略但收益最大的一项，尤其依赖多的项目，能省掉一半时间。

rules限定只在合并请求时触发，避免每次推送到任何分支都跑，浪费算力也制造噪音。

--tag "req-${REQ_ID}"把需求编号打进产物标签，这是打通"需求到产物"链条的最后一环。

6. 几个反复出现的问题及排查思路

跑了大半年，有几类问题反复出现。我把当时的排查路径写下来，比直接给结论有用——因为每个团队的具体原因可能不一样，但查的思路是通用的。

6.1 合并冲突越解决越多

有段时间我们陷入了怪圈：一个分支解决完冲突推上去，第二天又冲突了，而且冲突文件一次比一次多。

我的排查顺序是这样的：

第一步，看冲突集中在哪些文件。统计下来 70% 的冲突集中在三个文件上，都是几百行的"上帝类"。这已经说明问题了：不是流程问题，是结构问题。所有人都在改同样的几个大文件，冲突是必然的。

第二步，看分支存活时长。拉了一下数据，那段时间分支平均存活 6.8 天，最长的 12 天。分支活得越久，偏离主干越远，合并时的差异面越大。

第三步，看有没有格式化提交混进来。查提交历史发现，有个同事的编辑器在保存时自动格式化了整个文件，一个只有两行逻辑改动的提交，diff 显示改了三百行。这种提交一进来，后面所有人的行号全乱，冲突必然爆发。

对应的三个处理：

• 上帝类拆分，这是根本解法，但慢，我们在迭代里留了固定的技术债额度慢慢做，同时先约定改动这几个文件必须提前在群里说一声，避免多人同时动。
• 缩短分支寿命，硬性要求五天以内必须合并，超过就拆成更小的需求。这条规则落地后，冲突量直接降了一半。
• 统一格式化配置，把格式化配置文件放进仓库，编辑器统一读取，并在流水线检查里加一条"纯格式化提交必须单独成支"的规则。

注意：解决冲突时千万别用"我的版本覆盖全部"这种操作。我看过一次事故，有人图快用了这招，把另一个分支三天的改动全冲掉了，因为被覆盖的代码在他本地根本不存在，工具不会有任何提示。

6.2 迭代末期流水线集中飘红

我们连续三个迭代都是最后两天流水线大面积失败，前面十天基本全绿。一开始以为是巧合，后来发现是稳定的规律。

排查的思路是从最早失败的那条开始看，而不是最新的。因为后面的失败经常是被前一个带崩的（比如依赖装不上、镜像拉不到、端口被占）。翻到那条最早的，错误信息很直白：测试环境数据库连接数打满。

顺着往下查根因，是三个问题叠加：

第一，环境漂移。测试环境是手动配的，有人改过配置没人记录，和配置文件里的不一致。迭代末期集中跑全量测试，把隐藏的差异全暴露了。解决办法是把测试环境也用配置描述出来，随流水线一起创建和销毁，不再手动改。

第二，共享测试数据。所有测试用例共用一个测试库，前面的用例插入的数据影响了后面用例的断言。平时只跑改动的模块问题不大，末期跑全量就炸了。改成每个用例自己在事务里准备数据、跑完回滚。

第三，并行任务抢资源。流水线并行跑多个任务，都去连同一个测试库，连接数瞬间打满。加了并发限制，同环境的并行任务最多两个，问题消失。

这三个问题平时都藏得很好，只在压力集中时暴露。所以我现在有个习惯：每周至少安排一次全量流水线跑，不要等到末期。提前暴露比集中爆发成本低太多。

另外提一个反直觉的观察：那段时间我一度想用失败率做团队考核，被自己拦住了。因为一旦这么做，最理性的应对方式就是少跑测试、或者把不稳定的用例跳掉，指标立刻变好看，问题一点没解决。指标只能用来找原因，不能用来定责任。

说说我自己这两年最大的一个转变。刚开始接手这套东西的时候，我特别热衷于把能开的规则全开、能加的检查全加，总觉得约束越严质量越好。结果是团队怨气很重，各种绕过规则的小动作层出不穷，规范文档越写越厚，实际执行越来越变形。

后来我明白了一件事：规范的存活率不取决于它有多完备，而取决于它给开发者带来的即时收益能不能覆盖遵守成本。提交信息规范之所以能活下来，是因为它在两秒内弹出来、帮开发者省了思考成本；分支保护之所以能活下来，是因为它拦下的那些事故大家都亲眼见过。反过来，那些纯粹为了"应该规范"而加的东西，无一例外全死了。所以现在每次要加一条新规则，我都会先问自己：这条规则是为了解决一个真实发生过的问题，还是为了让我心里踏实？如果答不上来前半个问题，就不加。

另外一个小技巧分享给正在做类似改造的人：先挑一个三五个人的小团队试点，跑完一个完整迭代再推。你会在这个小范围里踩到八成的坑，而且修复成本很低。直接全团队铺开，一旦某个配置不当，阻塞的是所有人，那时候就没有从容调整的空间了。