一、问题背景:从“推master”到发布回滚噩梦
先说结论:我们团队15个人,后端9个、前端4个、测试2个。2022年下半年,大家的协作方式基本是“本地开发完直接push master”,偶尔拉个feature分支也是想起来才拉。结果就是:
- 每周平均3次发布回滚,最夸张的一周回滚了5次;
- 线上事故中约60%能追溯到“某次合并把别人未完成的代码带上线”;
- Code Review形同虚设,MR(Merge Request)平均挂26小时没人看,最后自己点合并;
- 没有CI,测试同学每次发版前手动跑一遍冒烟,耗时约2.5小时。
痛定思痛,我们花了两周把Git工作流、Code Review和CI/CD重新梳理了一遍。下面是我们最终落地的方案,配置都是真实在跑的,版本号也标清楚,方便你直接抄。
二、环境与版本
- Git:2.40.1(服务端GitLab自带,客户端统一升级)
- GitLab:16.4.1(CE版,自建)
- GitLab Runner:16.4.1,Docker executor,注册了3个runner
- Node.js:18.18.2(前端构建)
- Maven:3.9.5 + JDK 17(后端构建)
- pre-commit:3.5.0(本地钩子框架)
- Docker:24.0.7(构建镜像用)
三、方案设计:分支策略 + 保护规则
3.1 分支模型:简化版Git Flow
我们没用完整的Git Flow(develop/release/hotfix太绕,小团队扛不住),最终定的是:
main:生产分支,只接受来自release/*和hotfix/*的MR,且必须打tag(如v1.4.2);release/*:预发布分支,从main切出,测试验收通过后合回main;feature/*:功能分支,从main切出,命名规范feature/需求号-简述,比如feature/PROJ-231-order-export;hotfix/*:紧急修复,从main切出,修完同时合回main和当前release。
关键规则:feature分支生命周期不超过5个工作日。超过就说明拆得不够细,我们在周会上会点名。这条规则把长命分支的合并冲突从“每周必炸”压到了“偶尔”。
3.2 GitLab分支保护配置
main和release/*都开了保护,具体参数:
- Allowed to merge:Maintainer(只有TL和组长能合)
- Allowed to push:No one(任何人都不能直推)
- 勾选“Require approval from 1 approver”
- 勾选“Reset approvals on push”(防止先批准再改代码)
- 勾选“Require a successful pipeline”(流水线必须绿)
- 勾选“Require conversation resolution”(评论必须解决)
这些在GitLab 16.4的 Settings → Repository → Protected branches 里配,建议用API批量配,省得手点:
# 用GitLab API给main分支加保护,token需要api权限
curl --request POST \
--header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
--data "name=main" \
--data "push_access_level=0" \
--data "merge_access_level=40" \
--data "allow_force_push=false" \
"https://gitlab.example.com/api/v4/projects/123/protected_branches"
3.3 Code Review流程
我们定了几条硬规矩:
- MR标题必须带需求号,模板自动带出(
.gitlab/merge_request_templates/default.md); - 单个MR改动超过400行,reviewer有权直接打回要求拆分;
- Reviewer在4个工作小时内必须给首次反馈(我们用GitLab的SLA标签+钉钉机器人提醒);
- 至少1个approve才能合,
main的MR要求TL额外approve。
为了让reviewer不瞎看,我们加了.gitlab/merge_request_templates/default.md:
## 关联需求
PROJ-
## 改动说明
## 自测情况
- [ ] 本地跑通单测
- [ ] 本地起服务验证主流程
## 影响范围
四、核心实现:CI/CD与本地钩子
4.1 .gitlab-ci.yml 完整配置
我们的流水线分四段:lint → test → build → deploy(deploy只对main的tag触发)。缓存用Maven和npm的本地目录,实测把构建时间从7分12秒压到3分40秒。
# .gitlab-ci.yml GitLab 16.4
stages:
- lint
- test
- build
- deploy
variables:
MAVEN_OPTS: "-Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository"
npm_config_cache: "$CI_PROJECT_DIR/.npm"
# 缓存:key按分支区分,避免互相污染
cache:
key: "$CI_COMMIT_REF_SLUG"
paths:
- .m2/repository
- .npm
lint:
stage: lint
image: node:18.18.2
script:
- npm ci --prefer-offline
- npm run lint
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
- if: '$CI_COMMIT_BRANCH == "main"'
unit-test:
stage: test
image: maven:3.9.5-eclipse-temurin-17
script:
- mvn -B test -DskipITs
artifacts:
when: always
reports:
junit:
- target/surefire-reports/TEST-*.xml
expire_in: 7 days
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
- if: '$CI_COMMIT_BRANCH == "main"'
build-image:
stage: build
image: docker:24.0.7
services:
- docker:24.0.7-dind
script:
- docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA .
- docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
rules:
- if: '$CI_COMMIT_BRANCH == "main"'
deploy-prod:
stage: deploy
image: bitnami/kubectl:1.28
script:
- kubectl set image deployment/app app=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA -n prod
- kubectl rollout status deployment/app -n prod --timeout=180s
rules:
- if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/'
environment:
name: production
注意几个参数:--timeout=180s是我们踩坑后加的,之前默认无限等,一次卡死挂了40分钟;expire_in: 7 days防止artifacts把磁盘撑爆(我们被撑爆过一次,清了20G)。
4.2 本地pre-commit钩子
光靠CI太晚,等推上去才发现lint不过很浪费时间。我们用pre-commit 3.5.0在本地拦一道:
# .pre-commit-config.yaml
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.5.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-merge-conflict
- repo: https://github.com/pre-commit/mirrors-eslint
rev: v8.56.0
hooks:
- id: eslint
files: \.(js|vue)$
args: [--fix]
装完跑pre-commit install,之后每次commit自动检查。实测本地拦截了约70%的低级格式问题,CI里lint阶段的失败率从18%降到4%。
五、踩坑与优化
坑1:缓存key设计不当导致构建变慢。 一开始cache key用了全局固定值,结果不同分支互相覆盖,反而更慢。改成$CI_COMMIT_REF_SLUG后,main分支命中率91%,feature分支各自独立,构建稳定在3分40秒。
坑2:MR合并冲突集中爆发。 feature分支活太久,合并时冲突一片。我们加了钉钉机器人,每天上午10点把“存活超过3天的feature分支”推到群里,两周后平均分支寿命从8.2天降到3.6天。
坑3:流水线并发把runner打满。 发布日多个MR同时触发,3个runner不够用,排队20分钟。我们给resource_group加了限制,同一环境的deploy串行执行,同时把runner的concurrent从1调到2,排队时间降到3分钟内。
坑4:approve后改代码绕过review。 有人先拿approve再偷偷push。开了“Reset approvals on push”后彻底堵死,代价是改动后要重新等approve,但值得。
六、效果数据
跑了三个月,对比数据:
| 指标 | 改造前 | 改造后 |
|---|---|---|
| 发布回滚次数 | 每周3次 | 每月0.3次 |
| MR平均合并时长 | 26小时 | 4.5小时 |
| 冒烟测试耗时 | 2.5小时(手动) | 6分钟(CI自动) |
| CI lint失败率 | 18% | 4% |
| 平均feature分支寿命 | 8.2天 | 3.6天 |
| 构建耗时 | 7分12秒 | 3分40秒 |
七、总结
Git工作流这件事,工具配置是次要的,关键是几条硬规则要真的执行:分支短命、MR小步、review有时限、流水线必须绿。我们的配置不复杂,GitLab 16.4自带的能力基本够用,核心是把保护规则和CI门禁卡死,别给人留“绕过”的口子。如果你团队也在10-20人规模,这套简化版Git Flow + 强制CI的方案可以直接抄,改改项目ID和registry地址就能跑。下一步我们打算把deploy阶段接上Argo CD做GitOps,到时候再写一篇。