如果你的团队还在让每个开发者直接往主分支上点“Merge”那我强烈建议你读完这篇文章。我在Gas Town Refinery这个模拟项目上维护CI/CD流程时被这种“想合就合”的协作方式折磨到怀疑人生。主分支动不动就红跑完测试发现合进去的代码根本不是刚才审完的那一版回滚的时候又是一场混战。后来我把整个合并流程改造成了Bors风格的合并队列用批量合并代替零散合并主分支从此再也没有因为并发合入而垮掉。合并队列听起来像个高深的东西其实核心思路特别朴素让主分支永远停留在“刚刚通过完整验证”的状态所有PR都先排队攒够一批再一起验证、一起合入。这篇文章我会从为什么需要它讲起再到三个关键设计决策然后给出一个可以直接复现的核心实现最后聊聊我在Gas Town Refinery上踩过的真实坑。适合那些受够了主分支反复变红、想正经治理合并流程的开发和DevOps同学。1. 让主分支稳定从向Bors学习排队机制开始1.1 直接merge的日常战况先说点具体的。在没有合并队列之前Gas Town Refinery的仓库大概是这个样子五个开发者在各自的feature分支上忙碌谁先点完review谁就能把代码合进主分支。每个人合入之前CI都诚实地跑了一遍自己分支的构建和测试全部绿了以后才点下的Merge。但问题出在“合并完主分支”的那一刻——两个人几乎同时合入主分支上出现了同时对同一个配置文件做修改的冲突CI在合并后的代码上直接挂了。这种场景熟悉吧。直接合并的致命问题在于你验证的是自己分支的“孤立状态”但你合入后的代码是“多个分支叠加后的状态”这两个状态根本不一样。更难受的是一旦主分支挂掉所有人都得停下手头工作去修主分支因为其他人接着合就会在红地基上盖楼。我把这三个问题整理成一张表都是我曾经在项目里真实遇到过的现象根因直接后果并行合入后主分支变红验证对象过时测的不是合入后的代码全员被迫停下修复反复rebase消耗大量时间主分支持续不稳定重放成本高开发者每天浪费1小时回滚拖尸不知道哪个PR导致故障只能整体回退连带回滚无辜变更1.2 “先上车后买票”的批量合并哲学Bors风格的核心不是“更快地合”而是“更安全地批量合”。它借鉴了一个很朴素的道理一辆车坐满乘客再发车比一个人一辆车在路上跑要高效得多而且只要发车前做一次全车检查就行不用每上一个客人都把车拆了查一遍。放到代码里就是不要一个PR跑一次完整流水线然后立刻合并而是把排队等待的PR攒成一批先在“暂存分支”上把这些PR全部合并到一起跑一遍完整测试。测试通过以后把这一批按顺序真正合入主分支测试失败就二分排查是哪辆“车”拖累了全车人。这种模式天然具备一个巨大优势主分支的每一次推进对应的都是“一个跑过完整测试的合集”而不是“一个只在自己分支上跑过测试的散装PR”。我从把主分支从“每天都在受伤”的状态里解脱出来的那一刻起才真正理解Bors这句话不要相信任何没有在合并结果上跑过测试的东西。1.3 队列吞吐量与测试成本的直觉公式很多人会担心批量合并不会让合并变慢吗其实计算一下就明白了。假设单次CI从启动到全绿需要20分钟每天有10个PR要合。逐个合并的策略需要跑10次CI总耗时200分钟而且这200分钟是串行的期间主分支还要持续暴露在“随时可能被另一个PR污染”的风险里。批量合并如果一次能装5个PR10个PR只需要跑2次CI总耗时40分钟吞吐量直接翻了5倍。代价只是每个PR在队列里多等了一会儿。批处理节省的是“固定启动成本”——环境准备、依赖安装、基础设施调度这些开销并不会因为PR数量少而消失。所以我给你的第一个直觉公式是CI跑一次的成本越贵你就越应该拉大批量窗口。如果一套完整E2E测试要跑40分钟你还让每个PR单打独斗是对基础设施的极大浪费。2. 合并队列的三个核心设计决策先想清楚再动手2.1 批量窗口攒几个PR发一趟车最划算第一批要设计的是攒多少个PR再发车。这个数字不是拍脑袋定的而是取决于两个要素单次CI的固定成本以及批内冲突的概率。我倾向于用一个简单的算账方式环境准备和基础设施调度占CI总时长的比例越高批量窗口越该大。比如你用的是自建的流水线每次都要重新拉缓存、重建镜像一个10分钟的总流水线里固定成本可能占了6分钟那窗口完全可以拉到10个PR。如果是轻量级测试固定成本很低窗口小一点也无所谓因为批处理的边际收益不明显。但你也要小心窗口过大的反噬批内PR越多互相之间产生代码冲突的概率越大。一旦batch构建失败你需要二分定位参与排查的PR越多定位成本越高。我在实践中的经验是团队每天合并量少于20个PR时窗口设置为5左右最舒服——既能吃到批处理的红利又不会频繁触发batch内部冲突。2.2 验证对象保证“要合进去的东西”就是“测过的东西”这是整个合并队列的灵魂问题到底应该验证什么很多刚开始做合并队列的人这里就错了——他们拿“PR的最新提交”去跑CI跑完绿了然后直接把PR合到主分支上。但就在测试的那几分钟里主分支可能已经前进了好几个commit你合入后的最终状态根本没被验证过。Bors风格的解法是创建暂存分支把当前主分支的最新提交拉下来把本批所有PR的代码合并上去然后在暂存分支上跑完整流水线。只有暂存分支测试全绿才真正把这一批PR逐个合入主分支。合入的时候不需要再跑一遍测试因为这批PR合进去的结果和暂存分支上已经测过的状态是一模一样的。这个“一模一样”是设计上要死守的主分支在这期间必须被锁住不能有任何其他合入插入。合入完成后立即解锁让下一批继续。否则你验证了A版本合入了B版本队列就形同虚设了。2.3 合入时刻串行执行器才能杜绝并发第三个设计决策是“谁有资格合代码”。直接合并之所以乱是因为每个开发者都有权限合并等于有五个司机各开各的车。合并队列要求整个仓库只有一个“正在工作的执行器”它从队列里取一批验证合入期间其他所有合并请求全部阻塞。落到实现上通常是抢一个全局锁。锁可以用数据库行锁、文件锁或者分布式协调服务的临时节点保证同一时刻只有一个执行器在跑批处理就行。你不需要多么高深的分布式锁方案能保证“全局唯一”就够了。我在项目初期甚至直接用了一个“原子创建锁文件”的方法虽然简陋但确实管用哪怕进程重启了也能靠锁文件识别残留状态。3. 用脚本实现合并队列的核心运转逻辑3.1 队列数据结构deque加依赖表先把最基础的队列模型搭起来。我习惯用双端队列deque存等待合并的PR列表因为要支持从队首取数、失败时回退插回、超时后从队中移除这种操作。每个队列项至少包含PR编号、目标分支、最新提交SHA、进入队列的时间。CRITICAL点在于处理依赖关系。Gas Town Refinery里有不少PR是“依赖另一个PR先合入”的。比如后端先改了接口前端才能做联调。这种依赖关系不能靠队列顺序硬排因为队列顺序只代表入队时间不代表逻辑依赖。我在队列项里加了一个依赖字段指向它依赖的PR编号。调度器取数时如果发现队首PR的依赖还没合入就跳过它先看后面的PR否则就会出现“前面没有可以合入的后面全被堵死”的局面。from collections import deque import time class QueueItem: def __init__(self, pr_id, head_sha, merged_deps): self.pr_id pr_id self.head_sha head_sha self.merged_deps merged_deps # 已满足的依赖PR集合 self.enqueued_at time.time() class MergeQueue: def __init__(self): self.items deque() self.merged set() # 已经合入的PR编号3.2 批处理调度器凑车的过程就是不断merge试错调度器的逻辑其实就是一个“凑车”过程。我把主分支拉到本地然后从队首开始逐个尝试把PR的代码合并进暂存分支。合并成功的PR就加入本批合并出现冲突的PR先放回队伍里等着让后面的人先上来。为了避免无限循环我给“尝试入批”的操作设了一个上限先扫描整个队列的副本能合进来的都合进来然后统一排序、统一合并。如果同一批里PR A和PR B因为改了同一个文件而互相冲突调度器会按进入队列的顺序保留先来的抱歉地把后请出来的暂时移出队列。def build_batch(self, max_batch): batch [] tmp_branch fetch_main() # 拿到当前主分支最新状态 pending list(self.items) for item in pending: if len(batch) max_batch: break if not self.dependencies_met(item): continue if try_merge(tmp_branch, item.pr_id): # 试试合进来会不会冲突 batch.append(item) self.items.remove(item) # 冲突的留在队列里等下一批 return batch3.3 合并执行器从暂存分支到真正入主干调度器确定了这批人之后合并执行器就上岗了。执行器的职责是推送暂存分支、触发流水线、监听CI状态、根据结果决定合入或回退。这里有一个我强烈推荐的细节不要等到CI结果回来才去合并而是先把暂存分支推送到远端让CI系统直接跑暂存分支的任务。这样流水线测的代码和即将合入的代码就是同一个对象。CI全绿后执行器开始正式合入。我选择的方式是逐PR fast-forward合并到主分支而不是把暂存分支整个直接推到主分支。这样每个PR的提交历史还是保留的review记录不会乱将来回滚单个PR也更精确。git fetch origin main git checkout -b staging-branch origin/main for pr in batch; do git merge --no-ff refs/pull/$pr/merge -m Merge PR #$pr into staging done git push origin staging-branch执行器的工作状态机大概是等待锁 → 构建batch → 推暂存分支 → 等绿色 → 顺序合入主分支 → 释放锁。任何一步失败走失败处理分支核心思路是先把这批没合完的PR从暂存分支上拆干净再决定怎么回退。4. 依托现有CI平台落地少写一半代码说了这么多原理和脚本其实大部分团队不需要从零写一个完整的合并队列机器人。如果你用的是主流的代码托管平台加自带流水线完全可以让平台替你扛住最苦的“状态检查”环节你只需要把批处理和合并策略变成流水线里的几个任务。4.1 用“状态检查”当信号灯现代代码托管平台几乎都有“分支保护”和“状态检查”能力。你可以把主分支设成“不允许直接推送”只允许通过流水线任务来更新。这就是天然的合并队列信号灯流水线任务在跑主分支就是锁住的任务变绿合入才有权限。我把主分支保护规则简化为三步第一删除直接push权限第二要求所有PR合入前必须通过自动构建第三让流水线里的合并任务持有唯一的写权限。这样开发者点了Merge按钮也推不上去等于强制人们“走队列”。4.2 端到端流程从PR被approve到进队列到合入在Gas Town Refinery上我实际落地的流程是PR创建后先跑一遍针对该分支的基础检查让开发者尽快发现编译错误人工review完成后开发者加上一个“queue”标签流水线识别到这个标签就把PR自动加入合并队列。流水线里的“批量合并任务”会拉取当前队列中的待合并PR走前面说的batch逻辑推送到一个名为integration的分支。integration分支上有唯一一个一连串的流水线任务构建、单测、集成测试、E2E。这串任务全部通过就触发最后一步——合并器把本批PR逐个合入主分支并自动删除该批次相关的合并队列标签。这其实就是在用现成流水线的“多个串行Job”模拟了一个一次性执行器。这片土地上不需要你写任何bot进程所有状态都沉淀在平台的任务记录里排查问题时一目了然。4.3 失败兜底与恢复策略流水线跑红了以后最紧急的任务是快速定位“谁弄脏了整批”。我的兜底策略是这样设计的合入执行器在检测到集成分支失败时先自动把本批最后一个PR移出队列重新跑一次集成。如果还失败继续移除倒数第二个如此反复直到集成分支重新变绿——这本质上是一个从队尾逐步缩小range的线性排查法。成功定位到问题PR后把它留在队列里等开发者推送修复。其余PR按正常流程合入。这个方法比一次性把整个batch全部打回重来要人性化得多不会因为一个人的问题让其他四个人白白等待一整个验证周期。5. 批量合并实战踩坑记录5.1 batch构建失败时的“一拖三”与二分回退我第一次把合并队列跑起来的时候以为它的快乐很简单攒批、跑测、合入。结果第一次batch全红就把我整懵了。五个PR合在一起的集成分支构建失败我本能地一个接一个把PR往队列外挪跑了整整五轮完整流水线才定位到是第三个PR把一个公共依赖的版本锁坏了。这个“一拖三”的问题在于真凶可能不在最后一个位置。更聪明的做法是二分定位——把batch从中间拆成两半分别跑集成验证。如果前半通过、后半失败就把后半再二分。理论上每多跑一轮就能排除一半嫌疑对象比线性排查少跑好几轮流水线。代码上并不复杂就是把batch列表切成两段重新生成两个临时分支。def bisect_failures(batch): low, high 0, len(batch) while high - low 1: mid (low high) // 2 if integration_test(batch[low:mid]): # 前半段通过 low mid # 嫌疑缩到后半段 else: high mid # 嫌疑在前半段 return batch[low]这个优化的收益非常可观5个PR的batch出了故障线性排查最坏跑5轮CI二分只需要3轮10个PR的batch线性排查最坏10轮二分4轮。省下的全是真金白银的机器时间。5.2 队头阻塞一辆坏车堵住整条线合并队列里最令人血压升高的场景是某个PR因为依赖的另外一个PR还没合入一直赖在队首不肯走而它后面排着七八个好端端PR只能干等。这是典型的队头阻塞。我在队列设计里专门加了一个超时机制单个PR在队首停留超过预设时间调度器会把它暂时移出队列先让后面的PR形成批次发车。被移出的PR不会丢它会收到一条“你的PR长期未满足合并条件请检查依赖或解决冲突”的提醒。开发者处理完以后重新入队排到队尾。这里有个细节经验千万别对“队首之外”的PR做超时移除。如果某个PR不是队首但会挡住后面的人你把它移出去意义不大因为队首的logic不受影响。只有卡在队首的PR才真正阻塞全局。5.3 状态检查过期莫用旧SHA验证新代码最后一个坑非常阴险我称之为“状态过期”。想象一下这个场景一个PR在合并队列里等着它的最新提交SHA是abc123。流水线拿这个SHA跑了集成测试大量依赖下载和容器构建花了30分钟。就在流水线跑的这30分钟里开发者又往PR里推了一个修复提交SHA变成了def456。流水线跑完最终结果关联的是abc123这个旧SHA。但很多天真的实现会直接认为“这个PR测试通过了”然后就拿着def456合并。你以为你验证的是def456吗不你验证的是abc123甚至更早的版本。这个问题的解法很简单流水线关注的任务不是“PR是否通过”而是“指定SHA是否通过”。合入执行器在决定合并一个PR前必须重新拉取它的最新SHA与流水线验证的SHA比对不一致就重新验证。我在脚本里是直接把head_sha存进队列项合并前比对一次不一致就强行把PR拽回队列重新排队。这个设计能让合并队列在“快速推进”和“绝对安全”之间站稳脚跟。说实话从我第一次把合并队列跑通开始Gas Town Refinery的主分支就不再是团队的公共负担了。开发者们不需要时刻提防“主分支是不是又红了”review完之后加个标签剩下的事情由队列托管。我最真实的体会是合并队列没有让合并变慢它只是把原本被浪费在无休止修主分支上的时间重新还给了写代码的人。如果你也想彻底告别“合代码全靠运气”的现状按这篇文章的思路从批量窗口和暂存分支验证做起一定会有立竿见影的效果。最后送上一句让我收益最大的实战心法合并队列的核心不是“排队”而是“让每一次合入都有据可查让每一次验证都对得上最终结果”。这一句话想透了你自然知道该怎么调整你的flow。
