Gerrit与GitLab单向同步实战：配置详解与常见问题排查

1. 为什么需要Gerrit与GitLab单向同步在代码管理的工作流中Gerrit和GitLab各自扮演着不同角色。Gerrit以强大的代码审核机制著称而GitLab则更擅长作为Git仓库托管平台。很多团队既想保留GitLab现有的CI/CD流程又希望引入Gerrit的代码审核能力这就产生了双向系统集成的需求。想象这样一个场景你们团队已经在GitLab上建立了完整的自动化构建流程但缺乏严格的代码审核机制。如果直接迁移到Gerrit所有CI/CD流程都需要重写成本太高。这时候单向同步方案就派上用场了——Gerrit作为代码审核的守门人审核通过的代码自动同步到GitLab既不影响现有构建流程又增加了代码质量保障。我参与过的一个智能硬件项目就遇到过这种情况。硬件团队的构建脚本都深度绑定GitLab而软件团队需要严格的代码审核。通过Gerrit→GitLab的单向同步我们实现了两全其美开发者在Gerrit提交代码审核通过后自动同步到GitLab触发硬件构建整个过程无缝衔接。2. 环境准备与权限配置2.1 服务器基础要求开始配置前请确保拥有Gerrit服务器的管理员权限拥有GitLab服务器的管理员权限两台服务器网络互通建议内网环境已安装最新版OpenSSH实测7.9以上版本兼容性最佳建议先在测试环境验证整个流程。我在生产环境部署时就遇到过SSH版本不兼容的问题后来发现是测试环境用的OpenSSH 8.1而生产环境还是7.4导致密钥认证失败。2.2 双向SSH密钥配置Gerrit→GitLab方向配置登录Gerrit服务器生成密钥对ssh-keygen -t rsa -b 4096 -C gerrit_to_gitlab -f ~/.ssh/gerrit_gitlab_key将公钥添加到GitLab的authorized_keysssh-copy-id -i ~/.ssh/gerrit_gitlab_key.pub gitlab-usergitlab-serverGitLab→Gerrit方向配置登录GitLab服务器生成密钥对ssh-keygen -t ed25519 -C gitlab_to_gerrit -f ~/.ssh/gitlab_gerrit_key将公钥添加到Gerrit的authorized_keysssh-copy-id -i ~/.ssh/gitlab_gerrit_key.pub gerrit-usergerrit-server提示如果遇到Permission denied错误检查目标服务器的/etc/ssh/sshd_config中是否开启了PubkeyAuthentication选项2.3 SSH配置文件优化在Gerrit服务器上创建~/.ssh/config文件Host gitlab-server HostName 192.168.1.100 User git Port 22 IdentityFile ~/.ssh/gerrit_gitlab_key IdentitiesOnly yes在GitLab服务器上也创建对应的config文件Host gerrit-server HostName 192.168.1.101 User gerrit Port 29418 IdentityFile ~/.ssh/gitlab_gerrit_key IdentitiesOnly yes这样配置后我遇到过最头疼的密钥切换问题就再没出现过。之前每次同步都提示密钥错误后来发现是SSH默认会尝试所有可用密钥导致认证混乱。3. Replication插件深度配置3.1 插件安装与检查新版Gerrit默认包含replication插件可通过以下命令验证ls $GERRIT_SITE/plugins/ | grep replication如果没有找到需要手动下载插件wget https://gerrit-ci.gerritforge.com/job/plugin-replication-bazel-master/lastSuccessfulBuild/artifact/bazel-bin/plugins/replication/replication.jar cp replication.jar $GERRIT_SITE/plugins/3.2 配置文件详解在$GERRIT_SITE/etc/replication.config中添加[remote android-projects] projects android-.* # 支持正则匹配项目名 url ssh://gitgitlab-server/android/${name}.git push refs/heads/*:refs/heads/* push refs/tags/*:refs/tags/* push refs/changes/*:refs/changes/* timeout 30 threads 5 rescheduleDelay 60 authGroup Replication-Users # 对应Gerrit权限组关键参数说明rescheduleDelay同步失败后的重试间隔秒threads并发同步线程数根据服务器性能调整authGroup指定有同步权限的Gerrit用户组3.3 高级匹配模式对于大型代码库可以使用更灵活的项目匹配[remote kernel-sources] projects ^linux-.*|^android-kernel-.* url ssh://gitgitlab-server/kernel-mirror/${name}.git replicateOnStartup true # 启动时全量同步我曾经管理过一个包含200仓库的项目使用这种模式极大简化了配置工作。只需要维护一个replication.config文件就能自动同步所有匹配的仓库。4. 项目同步实战操作4.1 现有GitLab项目接入在Gerrit创建同名项目ssh -p 29418 gerrit-admingerrit-server gerrit create-project \ --parent All-Projects \ --submit-type REBASE_IF_NECESSARY \ android/platform/frameworks/base初始化Gerrit仓库cd $GERRIT_SITE/git rm -rf android/platform/frameworks/base.git git clone --bare ssh://gitgitlab-server/android/platform_frameworks_base.git mv platform_frameworks_base.git android/platform/frameworks/base.git注意目录结构必须与Gerrit项目路径完全一致4.2 新项目开发流程开发者在Gerrit克隆项目git clone ssh://developergerrit-server:29418/android/platform/frameworks/base提交代码变更git commit -m 优化蓝牙协议栈性能 git push origin HEAD:refs/for/master审核通过后变更会自动同步到GitLab。可以通过以下命令验证git ls-remote ssh://gitgitlab-server/android/platform_frameworks_base.git4.3 分支管理策略对于长期维护的分支建议在replication.config中添加特殊规则[remote stable-branches] projects android/platform/frameworks/base url ssh://gitgitlab-server/android/stable/${name}.git push refs/heads/stable-*:refs/heads/*这样配置后所有stable-开头的分支都会同步到独立的GitLab仓库便于区分开发分支和稳定分支。5. 常见问题排查指南5.1 同步失败日志分析查看Gerrit的复制日志tail -f $GERRIT_SITE/logs/replication_log典型错误1权限不足ERROR: Permission denied (publickey)解决方案检查SSH密钥是否配置正确确认GitLab仓库有写入权限测试SSH连接ssh -Tv gitgitlab-server典型错误2网络超时TimeoutException: Connection timed out解决方案增加timeout参数建议至少30秒检查网络防火墙设置考虑使用内网专线连接5.2 密钥格式问题如果遇到invalid privatekey错误可能是密钥格式不兼容。解决方法转换密钥格式ssh-keygen -p -m PEM -f ~/.ssh/gerrit_gitlab_key在replication.config中指定密钥类型[ssh] keyType RSA # 或ECDSA/ED255195.3 部分引用不同步如果发现tags或特定分支没有同步检查push配置是否包含所有需要的refsGitLab端是否有同名refs导致冲突Gerrit权限设置是否限制了某些refs的推送5.4 性能优化建议当同步大量仓库时增加threads参数但不要超过CPU核心数设置rescheduleDelay避免频繁重试考虑分批次同步关键仓库监控Gerrit服务器负载情况我在处理一个包含500仓库的项目时将threads从3调整到8后全量同步时间从6小时缩短到40分钟。6. 最佳实践与经验分享6.1 权限管理策略建议在Gerrit中创建专门的复制权限组ssh -p 29418 gerrit-admingerrit-server gerrit create-group Replication-Operators ssh -p 29418 gerrit-admingerrit-server gerrit set-members \ --add service-accountcompany.com \ Replication-Operators然后在project.config中配置[access refs/*] exclusiveGroupPermissions read read group Replication-Operators push group Replication-Operators6.2 监控方案设计推荐监控指标同步延迟时间失败同步次数队列积压任务数可以使用Prometheus收集Gerrit的JMX指标scrape_configs: - job_name: gerrit static_configs: - targets: [gerrit-server:9986]6.3 灾备恢复方案建议配置双活同步[remote gitlab-backup] url ssh://gitbackup-gitlab-server/android/${name}.git replicateOnStartup false rescheduleDelay 300我在实际运维中就遇到过主GitLab宕机的情况幸好配置了备用同步目标整个切换过程对开发者完全透明。6.4 版本升级注意事项升级Gerrit时先备份replication.config检查插件兼容性列表在测试环境验证同步功能建议在低峰期执行升级有次我们Gerrit从2.15升级到3.0时就因为没检查插件兼容性导致同步中断了12小时这个教训让我至今记忆犹新。