1. 为什么团队需要Gerrit这种“重流程”评审工具聊到代码评审很多人第一反应是GitHub的Pull Request或者GitLab的Merge Request。这类工具把评审做成一个“功能”开个PR、几个人、聊几句、approve、合并完事。我刚开始接触Gerrit时也是类似心态明明PR用得好好的为什么要换一个看起来“又傻又硬”的系统甚至第一次在Gerrit上推送代码还闹出过笑话——我直接把代码推到refs/for/master之外的分支结果同事到处找我的变更都找不到。但真正在严格分工、多人协作的工程团队里干过一段时间后我逐渐理解了Gerrit的设计逻辑它不是把Code Review做成一个功能而是把它做成了代码入库的必经关卡。一个变更想要真正合入主分支至少要经历Change创建、多个Patch Set更新、评审人打分、CI验证、Submit合入这几个环节任何一个环节没完成代码就只能悬在评审系统里进不了任何人的工作区。换句话说GitHub的PR是“先入库再讨论”Gerrit是“先讨论再入库”。这个先后顺序的差异决定了Gerrit天然比PR流程更适合那些不允许代码轻易入库的保守型项目比如要保证每条提交都有明确日志、每个变更都经过至少两位评审人、每次合入都不能破坏构建结果的架构级项目。这篇文章我打算把Gerrit从安装部署、核心概念到日常使用、评审操作、问题排查整个串一遍。如果你正准备在团队内推行Gerrit或者你刚被分配了一个必须使用Gerrit的项目、正在为“推送代码还要带Change-Id”这种要求发愁这篇文章应该能帮你把大部分常用场景跑通。2. 本地环境搭建用Docker快速起一套可折腾的Gerrit2.1 为什么建议先用Docker而不是直接裸装Gerrit本身是个Java应用依赖Git、Java、数据库默认是H2生产环境一般换PostgreSQL或MySQL。直接部署到实体机上当然可以但如果你只是学习或者做小范围试验最省心的方式是用Docker把整套环境包起来。我自己常用的一个简化命令是这样docker run -d -p 8080:8080 -p 29418:29418 \ -e AUTH_TYPEDEVELOPMENT_BECOME_ANY_ACCOUNT \ --name gerrit gerritcodereview/gerrit解释一下这里的关键点8080是Gerrit的Web UI端口浏览器访问用这个。29418是SSH端口git push/pull走这个端口。AUTH_TYPEDEVELOPMENT_BECOME_ANY_ACCOUNT是一个极其重要的配置允许你在登录页随便输入一个用户名就能“变成”那个用户。生产环境绝对不能这样配但本地做实验时这意味着你可以不用配复杂的OAuth或LDAP立刻模拟多个评审人账号非常方便。启动后浏览器打开http://localhost:8080第一次会让你创建一个管理员账号。在DEVELOPMENT_BECOME_ANY_ACCOUNT模式下你甚至不需要真注册输入任意名字就能进去。我习惯创建一个叫admin的账号用它来做初始配置再创建一个alice和一个bob来模拟不同的开发者。2.2 记住这三个核心配置项虽然Docker镜像开箱即用但有两个地方我建议你启动之前就考虑清楚不然之后改起来麻烦。一个是etc/gerrit.config中的gerrit.ownerGroup和auth.type这决定权限的底层逻辑。默认配置适合单机体验但你要在本地模拟多人协作至少要理解auth.type改变后用户的来源是不同的DEVELOPMENT_BECOME_ANY_ACCOUNT意味着任何人可以伪装任何人这是测试利器也是生产环境的噩梦。另一个是数据库。H2适用于几十人的小团队但如果你要压测或者模拟大仓库至少换成PostgreSQL。我在Docker里通常再加一个PostgreSQL容器然后改gerrit.config的数据库连接这样Gerrit和数据库生命周期分开不会因为容器重建就把评审记录全丢了。提示Gerrit的数据分两部分——仓库数据存在git目录里元数据评论、打分、用户信息存在数据库中。只备份git目录而忽略数据库迁移后Change历史会全部丢失这点一定要记住。2.3 安装完必做的健康检查容器起来后不建议直接开始建项目先确认三件事Web界面能不能打开登录页是否正常渲染。SSH端口是否通ssh -p 29418 adminlocalhost能进到Gerrit的交互式shell说明SSH正常。用管理员账号进后台检查“Projects”列表里默认有没有All-Projects和All-Users两个项目。如果没有它们说明初始化没完成通常等几分钟再刷新。这三项确认后环境就算基础可用。接下来就要去理解Gerrit最关键的几个概念否则你创建完项目也不知道怎么把代码推上去。3. 核心概念拆解Change、Patch Set、打分与Submit3.1 Change到底是什么在许多Git平台里代码变更的载体是“提交”Commit。但在Gerrit里顶层概念是一个叫做Change的对象。我用一句通俗的话解释Change就是“一次要解决某个问题的所有版本的总和”。比如你要给某个登录模块加一个找回密码功能你最初写了几百行代码提交到Gerrit这个叫Change的“第1版”然后评审人说密码重置链接少了过期逻辑你改了代码再次推送这仍然属于刚才那个Change只是多了一个Patch Set 2后来又发现邮件模板有问题再改一次就是Patch Set 3。所以一个Change从生到死可能经历多个Patch Set。每个Patch Set对应一个Git Commit但Change本身不等于任何一个Commit。这个概念新人最容易混淆因为你在网页上看到的“Change 48273”下面列着“Patch Set 2”之类的条目实际上你要评审的内容永远是最新Patch Set相对第一个Patch Set的变化。在命令行下所有的Change都有一条唯一的Change-Id。这个ID长这样Iabc123def456...它是通过Git提交信息里的Change-Id:行来关联的。一个Change的多个Patch Set靠的就是commit message里相同的Change-Id。3.2 灵魂拷问为什么需要Change-Id它是怎么生成的Gerrit官方提供了commit-msg钩子来自动给每个新提交生成Change-Id。这个钩子在项目初始化的时候需要手动安装。我见过太多团队没装这个钩子导致每次推送都报“missing Change-Id in commit message footer”错误。安装方式有三种在Gerrit Web界面的“Projects - 你的项目 - Code Review - commit-msg hook”下载钩子文件放到本地仓库的.git/hooks/目录下并加上可执行权限。从Gerrit服务器上直接拷贝scp -p -P 29418 adminlocalhost:hooks/commit-msg .git/hooks/在网页上通过“Browse - hooks”路径手动复制内容。装完钩子后你每次执行git commit钩子会自动在commit message末尾追加一行Change-Id: Ixxxx。如果你在已有Change基础上修改后再提交就会发现Change-Id保持相同于是被Gerrit识别为同一个Change的新Patch Set。一个实用但反直觉的提醒如果你在本地用git commit --amend修改了一个已经推送到Gerrit的commitcommit message里保留着原有的Change-Id那你再次推送后会更新原来的Change但如果你复制了commit却改了Change-Id则会生成一个全新的Change。项目里规定“每个Change对应一个问题”正是基于这个机制。3.3 评审打分到底谁说了算从-2到2的含义Gerrit里没有“approve按钮”而是打分制。每个评审人可以给当前Patch Set打一个分数关键分数有两类分值含义影响2我强烈认可可以合入达到合入门槛之一1还不错但希望再看看不阻塞0无意见中性-1有疑虑但不算严重不阻塞但提醒作者-2反对不该合入直接阻断Submit如果你做过开源社区的维护者对这个区间应该不陌生。核心思想是让“合入”这件事需要明确的2授权而不是简单地“看起来没人反对就合”。这里有一个容易漏掉的点Verify验证和Code Review评审是两类不同的标签。CI系统比如Jenkins或Gerrit CI通常会在验证标签Verified上打分1表示构建和测试通过-1表示失败。而人工评审打的是Code Review标签。最终一个Change能被Submit必须同时满足“Code Review 2”和“Verified 1”。如果你创建项目时没有配置好Submit规则就会出现评审人明明全打了2Change仍然显示“Needs Verified”的尴尬情况。所以我在第4节会专门说一下怎么设置合入规则。3.4 Submit、Merge和Rebase到底做了什么Gerrit里的Submit表示把Change合入目标分支。但同样叫Submit背后有三种策略Merge Always、Merge If Necessary和Rebase Always。Merge Always无条件生成一个额外的merge commit把Change合并进来。Merge If Necessary如果目标分支自Change创建以来没变化就快进合并否则用merge commit。Rebase Always先把Change的补丁Rebase到目标分支顶端再快进合入保证历史是一条直线。我个人的偏好是在团队里用Rebase Always或Merge If Necessary视图更干净也方便回溯。如果你用Rebase Always要注意它会产生新的commit哈希本地如果还保留着旧commit之后推送时需要特别注意同步否则可能出现“non-fast forward”之类的错误。3.5 依赖的Change一个Change依赖另一个Change是怎么回事在实际开发中你经常需要先改A模块再基于这个改动改B模块。在Gerrit里如果你把两个Change先后推送到同一个目标分支并且后一个Commit的父Commit就是前一个CommitGerrit会自动建立“depends on”关系。你会在Web界面的Change详情页看到一行“Depends On Change 12345”。此时如果前一个Change被合入后一个Change会自动从“依赖中”状态变成可合入状态如果前一个被放弃或删除后一个Change的合入也会被阻塞。这种依赖关系对大型改动拆分特别有用你可以把一个大功能拆成多个小Change每个Change可独立评审但逻辑上保持顺序。Gerrit界面上会自动形成一条链条评审人顺着逐个Review体验比把几百个文件塞进一个PR里要舒服得多。4. 创建项目与权限配置从裸仓库到可协作开发4.1 创建项目时必选的几个项在浏览器中进入“Projects - Create New Project”需要填写Project Name建议用team/common或project/service这种带层级/团队前缀的方式避免项目多了以后管理混乱。Initial Branch通常填master或main按你的团队习惯来。Empty Commit建议勾选。否则Gerrit会默认创建一个空提交作为初始提交这会导致你push代码时出现奇怪的“ref”异常。选上这个选项Git库就会是一个百分之百的裸仓库什么都不含。创建完之后你会进入“Project”信息页。此时在“General”里能看到这个项目的git仓库地址形如ssh://adminlocalhost:29418/team/common如果用的是HTTP方式则是http://localhost:8080/team/common4.2 权限配置的“三层修炼”权限是Gerrit里最容易把人绕晕的部分因为权限不只挂在项目上还挂在引用refs上。即使你能浏览项目也不代表你能推送代码即使你能推送代码也不代表你能给别人的Change打分。我的建议是不要一上来就细抠每一行ACL先把三个层级关系搞清楚全局权限挂在All-Projects上。比如能否创建项目、能否管理服务器。项目级权限挂在具体项目上但具体继承自All-Projects。引用级权限形如refs/*、refs/heads/*、refs/for/*。同一个项目里你可以在refs/heads/*上设置“不允许直接推送”在refs/for/*上设置“允许所有人推送”这就能实现“代码必须通过评审才能合入”的核心约束。我自己在初始化一个项目时通常会对refs/heads/*设置Push权限为Deny只允许管理员通过Submit合入而对refs/for/*设置Push权限为Allow一般用户通过推送Change触发评审。这样一来普通的git push origin master会被拒绝而git push origin HEAD:refs/for/master才能成功创建Change。打开“Projects - 你的项目 - Access”页面可以看到一个类似下面这样的表格。我会手动添加常规的权限条目refs/heads/* Read: ALL (或项目成员组) Push: allowed for Registered Users ? 不该行改为Deny Label Code-Review: -2..2 for maintainers Label Verified: -1..1 for CI这里要特别强调Push对refs/for/*的权限并不等于你可以无限制推任意数量Change。如果你设置的是PushPush Merges或Create Reference这些子权利还是要按需要取舍。限制“普通用户只能推refs/for不能推refs/heads”是Gerrit保证评审流程不失效的根。4.3 用一个脚本搭建从零到可推送的最小环境如果你跟我一样喜欢命令行可以用下面这套流程快速搭建一个实验项目。假设本地已经用Docker起了Gerritadmin账号存在。首先在Web界面创建项目test/demo或者直接用REST API这里不用API演示避免篇幅过长。然后在本地git clone ssh://adminlocalhost:29418/test/demo cd demo # 安装commit-msg hook scp -p -P 29418 adminlocalhost:hooks/commit-msg .git/hooks/ chmod x .git/hooks/commit-msg echo # Demo Project README.md git add README.md git commit -m Add README # 推送到评审队列 git push origin HEAD:refs/for/master此时如果你是管理员大概率这个Change会直接变成NEW状态但因为还没有任何评审分不能合入。我们需要再模拟一个评审账号。在DEVELOPMENT_BECOME_ANY_ACCOUNT模式下打开Web UI退出当前账号输入alice登录注意密码随便填这就是一个新的用户了。在“Settings - Identities”里可以看到自己的用户名。然后用alice打开刚才的Change打上Code Review 2和Verified 1点击“Submit”。这个Change就正式合入了。这个流程走一遍你对Gerrit的整个“推代码-评审-合入”闭环基本就有体感了。接下来我们进入到日常开发中更具体的高频场景。5. 日常开发流程实操提交、修改、多分支协作5.1 Clone项目时容易忽略的“用户身份”问题Gerrit用SSH时用户名不是你的Git邮箱而是你在Gerrit系统里的用户名。最常见的问题是Permission denied (publickey).看似是密钥没配好其实很可能只是SSH的用户名不对。要么在~/.ssh/config里给Gerrit服务器单独配置User字段Host gerrit-server HostName localhost Port 29418 User admin IdentityFile ~/.ssh/id_rsa要么在Clone地址里直接写明用户ssh://adminlocalhost:29418/test/demo。登录后建议在“Settings - SSH Keys”里上传你的公钥。如果是用HTTP方式则在“Settings - HTTP Credentials”生成一个密码串用这个密码串当Git密码。5.2 推送代码到refs/for的完整解剖这是Gerrit最有特色的一点也是新手最难以理解的部分。普通的Git推送推到refs/heads/master就是直接把分支更新了。但Gerrit定义了一个“魔法引用”refs/for/master推送到这个引用的commit并不会真的去更新master分支而是创建了或更新了一个Change。具体指令git push origin HEAD:refs/for/master这个命令里HEAD表示推送当前检出的commit目标是refs/for/master。Gerrit收到后会做以下事情检查commit message里有没有Change-Id。如果没有Change-Id直接报错并提示你运行commit-msg钩子。如果有Change-Id查找是否已有同ID的Change有就把这次推送的commit作为新的Patch Set挂到同一个Change下。没有创建一个新的Change并用这次commit作为Patch Set 1。因此你完全可以把refs/for/master理解成一个“提交评审入口”进入这个入口的代码并不会直接污染主分支而是先出现在评审池里。5.3 如何在已有Change上补充新版本开发过程中评审人让你改一行代码你改了本地后如果只是git commit --amend并推送Change-Id会保留于是自动更新为新的Patch Set。但如果这个Change已经有多个Patch Set而且你本地拉的代码比较旧我推荐按这个步骤走git fetch origin refs/changes/48/48273/3 git checkout FETCH_HEAD # 修改代码 git add . git commit --amend --no-edit git push origin HEAD:refs/for/master注意refs/changes/48/48273/3是Gerrit为每个Patch Set暴露的内部引用。48是Change号除以100的取整前缀48273是Change号3是Patch Set编号。这个引用路径看上去反直觉但你只要记住它是“第3版Patch Set的提交”就可以了。---在新手阶段不需要记住这些引用路径的生成规则。用git fetch origin refs/changes/...前可以直接在Web界面Change详情页的“Download”下拉菜单里找到Checkout命令复制到本地执行即可。Gerrit会自动给出正确的ref。5.4 同时维护多个分支的实践如果一个项目有master和release/2.0两个分支你需要往两个分支分别提交修复时常规做法是各自创建Change但Gerrit里也可以做到一套代码改动同时推送到多个目标分支git push origin HEAD:refs/for/master HEAD:refs/for/release/2.0只要commit message里的Change-Id相同会在两个分支下各生成一个Change不同的Change号。这在维护老版本时很实用。不过要注意这两个分支上的Change是独立评审、独立合入的评审人需要分别给分。5.5 拉取和同步评审中的代码评审中的代码还没合入主干但你或许需要配合联调。这时候不要直接git pull因为refs/for不是在本地仓库的分支上。正确方法是git fetch origin refs/changes/48/48273/5 git checkout FETCH_HEAD或者如果在Gerrit Web页面对应的Change页选择“Download - Cherry Pick”可以产生一个本地分支并把对应commit捡到上面git fetch ssh://adminlocalhost:29418/test/demo refs/changes/48/48273/5 git cherry-pick FETCH_HEAD这样你就可以在本地基于评审中的Patch Set开展工作。同样的方式也适用于CI或打包系统拉取评审版本。这个能力是Gerrit和GitHub最不一样的地方评审中的代码也是可以通过稳定的ref被其他工具消费的。6. 评审界面的操作细节从打分到合入6.1 Change详情页信息解读打开一个Change详情页你会看到左侧有一列信息StatusNew / Merged / Abandoned。New表示待在评审池里Merged表示已合入Abandoned表示被放弃。Owner谁创建的Change。Reviewer目前被指派的评审人。Project / Branch属于哪个项目、目标是哪个分支。Patch Set当前是第几个版本点击可以对比任意两个版本。右侧则是评论区和打分按钮。如果你有权限会在页面顶部或底部看到Code Review -2 -1 0 1 2和Verified -1 0 1下面还有Submit按钮。我接触的很多新人会问“为什么我点了2但Submit还是灰的”答案往往就是Verified没通过或者你没有Submit权限。这一点在第3.3节说过但实际操作中真的很容易忽略。6.2 行内评论Inline Comment是评审的核心Gerrit的行内评论体验非常规矩你可以精确到某一行代码留言所有的评论会作为“评论”与Patch Set关联而不是像即时聊天一样零散出现。当你在代码某一行点“Add Comment”时可以勾选File Comment或Line Comment。如果是跨行代码逻辑问题建议明确说明是general comment还是特定行引发。评审人之间还可以在这些评论下进行回复会形成一个小对话串。我的习惯是所有评论都要是可执行的尽量给出修改方案或至少给出排查方向。只写“这段代码有问题”而没有建议作者往往要在评论区追问三轮才能明白你的意思。既然Gerrit本身就是为“慢而正式”的评审设计评论更不应该含糊。6.3 合并前检查依赖链不要盲点Submit当你在评审一个由多个Change组成的依赖链时在页面的Related Changes标签页里能看到它们之间的依赖关系图这里是列表式展示不是可视化图表。如果某个Change标着“Needs Rebase”说明它和当前目标分支已有冲突不能直接合并。此时有两种解法在Change页点击Rebase按钮让Gerrit自动把当前Change变基到目标分支顶端。在本地用git fetchgit rebase手动变基后重新推送。我建议优先用页面上的Rebase因为Gerrit的rebase会保留Reviewer评论和原Change号。手动rebase容易不小心改变Change-Id导致出现一个全新的Change评论文案全部丢失。6.4 把CI集成到评审流程很多团队的Gerrit页面里每次推送新Patch SetCI系统会自动给Verified标签打1或-1。这是通过Gerrit的Stream Events或REST API实现的。搭建流程大致是在Gerrit上创建一个专用CI账号例如jenkins。给该账号授予对应项目的Label Verified权限范围通常限定为-1..1。CI系统监听Gerrit事件或者轮询检查未验证的Change。CI跑完构建和测试后用REST API把结果打到对应Change上。这样做最大的价值是评审人在打分前就能看到CI是否通过不会出现“讨论得正high最后发现构建挂了”的无效评审。哪怕你不是CI专家搞清楚“Verified负分会阻断合入”这个设定也能帮你在权限配置时有的放矢。7. 常见问题与避坑经验实录7.1 推送时报错“missing Change-Id in commit message footer”这几乎是我见过最常见的新手错误。原因就一个commit message里没有Change-Id行。解决办法确认.git/hooks/commit-msg是否已安装并且有执行权限。如果它已安装但这条commit是之前没装时创建的需要先git commit --amend让钩子补上Change-Id。如果.git/hooks目录里没有commit-msg参考第3.2节重新安装。注意git commit --amend后如果commit message没有变化钩子可能不触发。此时可以故意在message末尾加一个空行或注释强制钩子运行生成Change-Id后再把多余内容删掉。7.2 推送被拒prohibited by Gerrit这条错误通常意味着你要推送到refs/heads/master但权限被拒绝了。结合我在第4.2节的做法普通用户无权直接更新分支是符合设计的。如果确认权限正确但还是被拒检查你是否推到了refs/for/master而不是refs/heads/master。我见过多个人把命令单词一打错就变成了直接推分支。正确的提审命令是git push origin HEAD:refs/for/master而不是git push origin master。7.3 Change显示多个Patch Set但本地代码“丢了”当你在本地用git commit --amend持续修改同一Change时commit哈希会不断变化。如果你在其他分支或机器上还保留旧哈希可能会误以为代码“回滚”了。实际上Gerrit只认Change-Id关联不追求本地commit和远程Patch Set的哈希一一对应。遇到这种情况不要用git pull去拉“Change”而是使用Change页的Checkout命令获取最新Patch Set。不要用本地commit的哈希去关联某个Change因为哈希会随amend改变。7.4 分支合入后本地master无法快进如果你把Change合并到master分支本地旧master在git pull时可能出现non-fast-forward或error: your local changes would be overwritten。这常常是因为Gerrit合入时用了rebase策略会生成新commit。解决办法是执行一次git fetch origin然后检查本地是否还有未推送的提交。如果有未推送提交先rebase后再推送如果没有直接git pull --ff-only同步。如果改动无关紧要也可以直接git reset --hard origin/master但前提是你非常清楚本地没有独有提交。7.5 在Windows环境下的路径与换行问题Windows用户经常遇到棘手的换行符问题。Gerrit本身不强制统一行尾但评审时如果看到全文件diff大概率是CRLF/LF差异导致的。建议在仓库根目录加.gitattributes强制文本文件统一用LF* textauto *.sh text eollf *.bat text eolcrlf否则评审人打开diff会发现每一行都变红了根本没法评审。这个坑非常影响协作效率提前做好配置能省很多事。7.6 我踩过最深的坑把“评审合入”误当成“合并”有一次我在一个项目里看到某个Change显示Merged就以为代码已经进到本地分支了但实际根本没有。原因是我配置了“Merge If Necessary”在目标分支没有新提交时Gerrit会做快进合并但本地旧分支如果和它实际没有什么关系就需要额外拉取。所以在团队里如果Gerrit作为唯一合入入口一定要让成员养成一个习惯所有分支同步都通过git fetch origingit rebase或git pull --ff-only进行不要直接git merge origin/master。原因在于Gerrit合入时可能会改写commit哈希而旧的本地引用会让人的认知发生错乱。8. 一些使用建议和长期习惯到这里Gerrit从环境搭建到日常使用的整个闭环算是走通了。最后分享几个我长期实践下来形成的习惯也许对刚接触Gerrit的人有帮助。第一不要把Gerrit当成一个Git托管服务器来用。它是“以评审为中心的代码协作系统”核心价值在于流程而不是存代码。如果你只是想找个地方放仓库、多人拉代码GitLab或Gitea的体验其实更轻。只有当你想严格约束合入门槛、记录每一次评审决策时Gerrit才明显有优势。第二小而频繁的Change永远比大而全的Change容易过审。在Gerrit上你完全可以只推一个几十行的小改动评审人看一眼就2。但如果你一次性弄出一个上千行的Change哪怕逻辑是对的评审人也会因为信息量太大而迟迟不敢合入。这种流程设计让团队很自然地倾向于小步提交、高频集成。第三Change-Id是Gerrit的灵魂。所有后续的操作——补充Patch Set、在评审中穿梭、让CI跟踪更新——都建立在Change-Id正确的基础上。所以一定要把写好commit message、安装好commit-msg钩子当作默认动作。我见过许多同事在提交新代码时忘了装钩子结果push失败后手忙脚乱其实只要养成“clone完先装钩子”的习惯后面就不会再为这个事头疼。第四权限模型值得多花十分钟想清楚。Gerrit默认情况下权限继承自All-Projects如果你在全局层面少了refs/for/*的Push权限所有项目都会出问题。我建议先把权限模型写在部署文档里至少说明refs/heads/*和refs/for/*的区别避免团队里每个人靠猜来配置权限。如果你正打算在团队内推行Gerrit祝你部署顺利如果你是在已有环境里被要求使用它希望这篇文字能让你少走一些我当年走过的弯路。
