一、问题背景:我们曾经把master当成了共享网盘
先说结论:小团队不设规矩,Git一定会退化成“带版本号的网盘”。
我们团队15人,后端8人、前端5人、测试2人,做的是一个SaaS后台。早期图省事,所有人直接往master推,commit message基本是“fix”“update”“再改一下”。很快就出现三个典型问题:
- 发布不可控。某次周三下午要发版,结果master上混进了两个没测完的功能,只能手动
git revert,回滚了4次才干净。 - 冲突集中爆发。两个人同时改同一个Service文件,谁后push谁解决冲突,平均每周6~8次合并冲突,有一次解冲突把别人的逻辑覆盖了,线上报错2小时。
- 评审形同虚设。没有MR(Merge Request)流程,代码质量全靠自觉,新人提交的SQL没加索引直接上线,慢查询告警。
痛定思痛,我们花了两周把工作流重做了一遍。下面是最终落地的方案,配置都是线上在跑的,可以直接抄。
二、环境与版本
- Git:2.39.2(服务端GitLab 16.4)
- GitLab CE:16.4.1,开启Merge Request与Protected Branch
- CI Runner:GitLab Runner 16.4,Docker Executor,2C4G
- 构建:Maven 3.9.6 + JDK 17,Node 18.19.0(前端)
- 镜像仓库:Harbor 2.9
选GitLab是因为我们本来就用它做代码托管,MR、保护分支、CI一条龙,不用额外搭Jenkins。
三、方案设计:分支策略
我们最终采用的是简化版Git Flow,没有引入release分支(发布频率高,release分支维护成本大于收益),核心是三条线:
| 分支 | 用途 | 生命周期 | 谁能推 |
|---|---|---|---|
master |
生产环境代码,永远可发布 | 永久 | 禁止直接push,只能MR |
develop |
集成分支,下一个版本的代码 | 永久 | 禁止直接push,只能MR |
feature/* |
功能开发 | 合入develop后删除 | 开发者 |
hotfix/* |
线上紧急修复 | 合入master和develop后删除 | 开发者 |
命名规范强制:feature/需求号-简短描述,例如feature/SAAS-1024-order-export。需求号来自Jira,这样MR和需求能对上,追溯方便。
保护分支配置(GitLab → Settings → Repository → Protected branches):
master:Allowed to merge = Maintainers,Allowed to push = No one,勾选“Require approval from 1 approver”develop:Allowed to merge = Developers + Maintainers,Allowed to push = No one
关键点:push权限设为No one,这样连管理员都不能绕过MR直接推,杜绝“我就改一行”的侥幸心理。
四、核心实现:MR流程与CI配置
4.1 MR与Code Review流程
规矩定死:
- 开发者从
develop切feature/*,本地开发,push到远端同名分支。 - 提MR到
develop,必须填:变更说明、影响范围、自测截图。 - MR必须满足4个条件才能合并(由GitLab的Merge checks强制):
- 至少1个Approve(核心模块要求2个)
- Pipeline必须通过
- 无未解决的Discussion
- 分支与目标分支无冲突
- 评审人24小时内必须响应,超时在群里@。
评审看什么?我们列了个简单清单贴在Wiki:SQL有没有索引、异常有没有吞、日志有没有打敏感信息、接口有没有做幂等、单测覆盖率是否达标(新增代码≥60%)。
4.2 CI/CD流水线配置
下面是.gitlab-ci.yml的实际内容(脱敏),分4个stage:verify → test → build → deploy。
stages:
- verify
- test
- build
- deploy
variables:
MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"
IMAGE_TAG: "$CI_COMMIT_SHORT_SHA"
# 缓存Maven依赖,实测把依赖下载从90s降到8s
cache:
key: "$CI_PROJECT_ID-maven"
paths:
- .m2/repository/
code-lint:
stage: verify
image: maven:3.9.6-eclipse-temurin-17
script:
- mvn -B checkstyle:check spotbugs:check -DskipTests
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
- if: '$CI_COMMIT_BRANCH == "develop" || $CI_COMMIT_BRANCH == "master"'
unit-test:
stage: test
image: maven:3.9.6-eclipse-temurin-17
script:
- mvn -B test
- awk -F, 'NR>1 {miss+=$4; cov+=$5} END {printf "line coverage: %.1f%%\n", cov*100/(cov+miss)}' target/site/jacoco/jacoco.csv
artifacts:
when: always
reports:
junit: target/surefire-reports/TEST-*.xml
expire_in: 7 days
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
build-image:
stage: build
image: docker:24.0.5
services:
- docker:24.0.5-dind
script:
- docker login -u "$HARBOR_USER" -p "$HARBOR_PWD" harbor.example.com
- docker build -t harbor.example.com/saas/backend:$IMAGE_TAG .
- docker push harbor.example.com/saas/backend:$IMAGE_TAG
rules:
- if: '$CI_COMMIT_BRANCH == "develop" || $CI_COMMIT_BRANCH == "master"'
deploy-staging:
stage: deploy
image: bitnami/kubectl:1.28
script:
- kubectl set image deployment/backend backend=harbor.example.com/saas/backend:$IMAGE_TAG -n staging
- kubectl rollout status deployment/backend -n staging --timeout=180s
environment:
name: staging
rules:
- if: '$CI_COMMIT_BRANCH == "develop"'
几个设计取舍说明:
- lint和单测只在MR和主干分支跑,feature分支的每次push不重复跑,省Runner资源。实测Runner并发从经常排队变成空闲。
- 单测覆盖率用awk从jacoco.csv算,不引额外插件,够用。低于阈值时我们没直接
exit 1,而是打印出来让评审人看——因为老代码覆盖率低,硬卡会让所有人卡在历史债上。新项目可以改成if [ $cov -lt 60 ]; then exit 1; fi。 - 镜像tag用commit short sha,不用latest,回滚时
kubectl set image指定旧sha即可,30秒回滚。
4.3 本地hook兜底
CI是最后一道关,但等CI跑完才发现commit message不规范太浪费时间。我们用commit-msg hook做本地校验:
#!/bin/sh
# .git/hooks/commit-msg
MSG=$(head -1 "$1")
PATTERN='^(feat|fix|docs|refactor|test|chore)(\(.+\))?: .{5,}'
if ! echo "$MSG" | grep -qE "$PATTERN"; then
echo "❌ commit message 不符合规范,示例:feat(order): 增加订单导出接口"
exit 1
fi
配合git config commit.template .gitmessage,新人clone后跑一下make init-hooks就把hook装好了。
五、踩坑与优化
坑1:MR太大,评审走过场。 最初有人一个MR改了43个文件、2000行,评审人看了5分钟点Approve。后来我们定规矩:单MR不超过400行有效变更(git diff --stat看),超了就拆。拆不动说明设计有问题。这条落地后,MR平均评审意见数从0.8条涨到3.2条,是真看了。
坑2:CI缓存key写错导致依赖串版本。 一开始cache key用$CI_COMMIT_REF_NAME,每个分支一份缓存,Runner磁盘两周就满了。改成$CI_PROJECT_ID-maven后共享缓存,磁盘占用降了70%。
坑3:dind构建镜像偶发超时。 docker:24.0.5-dind在2C4G Runner上构建大镜像时偶尔超时。加了DOCKER_TLS_CERTDIR: ""并给Runner调大到4C8G后稳定,构建耗时从平均3分10秒降到1分50秒。
坑4:hotfix合回develop被遗忘。 有次线上hotfix只合了master,两周后develop发版把bug又带回来了。后来在CI里加了个检查:master有新commit而develop没有对应merge时,发企业微信告警。简单粗暴但有效。
六、效果数据
落地3个月后的对比(数据来自GitLab Analytics和我们的周报):
| 指标 | 改造前 | 改造后 |
|---|---|---|
| 每周合并冲突次数 | 6~8 | 1~2 |
| MR平均评审时长 | 26小时 | 4.5小时 |
| CI平均耗时(MR流水线) | 无 | 6分20秒 |
| 因代码问题导致的线上回滚 | 月均2.3次 | 月均0.4次 |
| 新增代码单测覆盖率 | 约21% | 63% |
回滚次数下降是最直观的收益——不是因为大家变强了,是因为烂代码在MR阶段就被拦住了。
七、总结
Git工作流不是配几个分支就完事,核心是用工具强制约束人的惰性:保护分支禁push、MR卡pipeline、hook卡commit message,每一层都在减少“下不为例”。我们的配置不算精致,但胜在每条规则都有明确的触发点和后果,新人一周就能上手。
如果让我给正在踩坑的团队一条建议:先把master锁死,只允许MR合入,其他慢慢来。这一步的收益最大,成本最低。分支模型可以简化,CI可以later,但“主干不可直推”这条红线,越早立越好。