一、问题背景:从“推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流程

我们定了几条硬规矩:

  1. MR标题必须带需求号,模板自动带出(.gitlab/merge_request_templates/default.md);
  2. 单个MR改动超过400行,reviewer有权直接打回要求拆分;
  3. Reviewer在4个工作小时内必须给首次反馈(我们用GitLab的SLA标签+钉钉机器人提醒);
  4. 至少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,到时候再写一篇。