一、问题背景:我们曾经把master当成了共享网盘

先说结论:小团队不设规矩,Git一定会退化成“带版本号的网盘”。

我们团队15人,后端8人、前端5人、测试2人,做的是一个SaaS后台。早期图省事,所有人直接往master推,commit message基本是“fix”“update”“再改一下”。很快就出现三个典型问题:

  1. 发布不可控。某次周三下午要发版,结果master上混进了两个没测完的功能,只能手动git revert,回滚了4次才干净。
  2. 冲突集中爆发。两个人同时改同一个Service文件,谁后push谁解决冲突,平均每周6~8次合并冲突,有一次解冲突把别人的逻辑覆盖了,线上报错2小时。
  3. 评审形同虚设。没有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流程

规矩定死:

  1. 开发者从develop切feature/*,本地开发,push到远端同名分支。
  2. 提MR到develop,必须填:变更说明、影响范围、自测截图。
  3. MR必须满足4个条件才能合并(由GitLab的Merge checks强制):
  4. 至少1个Approve(核心模块要求2个)
  5. Pipeline必须通过
  6. 无未解决的Discussion
  7. 分支与目标分支无冲突
  8. 评审人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,但“主干不可直推”这条红线,越早立越好。