一、问题背景:我们为什么不得不重做Git工作流
我们团队做的是一个SaaS后台产品,后端Java 17 + Spring Boot 3.1,前端React 18 + Vite 4,仓库托管在GitHub Enterprise上,CI用的是GitHub Actions。团队15个人,分4个小组,日常并行开发的功能分支常年维持在20个以上。
迁移前的流程是典型的"简化版Git Flow":main保护,develop做集成分支,功能分支从develop切出,完成后合并回develop,发版时再合到main打tag。听起来没问题,但实际跑起来是这样的:
- 功能分支平均存活9.5天,最长的挂了3周,合并时冲突文件动辄十几个;
develop分支长期处于"半坏不坏"状态,谁都不敢保证它能部署;- Code Review靠口头催,PR平均开着26小时才有人看,看完提一堆意见又来回改三天;
- CI只在push时跑单测,镜像构建和部署是发版前手动触发,经常到发版日才发现构建脚本坏了。
转折点是去年Q3的一次发版:因为一个分支合并时漏掉了数据库迁移脚本,预发环境直接起不来,排查了4个小时。事后复盘,问题不在某个人,而在工作流本身——分支活得太久、反馈太晚、集成太迟。于是我们决定动手改。
二、环境与版本
先把家底列清楚,方便对照:
- Git 2.40.1,GitHub Enterprise Server 3.9
- GitHub Actions(企业版runner,4核8G,并发上限20)
- 后端:JDK 17.0.8,Maven 3.9.4,Spring Boot 3.1.5
- 前端:Node 18.17.1,pnpm 8.6.12,Vite 4.4.9
- 测试:JUnit 5.10,Testcontainers 1.19.1,Vitest 0.34.6
- 代码质量:SonarQube 10.2(社区版),ESLint 8.51
三、方案设计:为什么选Trunk-Based而不是继续修补Git Flow
我们评估了三个方向:
- 继续用Git Flow,加规则约束:比如强制分支存活不超过5天。但Git Flow的双长期分支结构天然鼓励"攒着再合",靠纪律对抗结构,成本太高。
- GitHub Flow:单
main分支 + 功能分支 + PR。方向对了,但缺Release分支的处理,我们还有对老版本打补丁的需求。 - Trunk-Based Development(TBD) :所有人往
main(trunk)合,分支存活控制在2天内,大功能用Feature Flag包起来;发布用短期release分支或直接打tag。
最终选TBD,核心设计如下:
main是唯一长期分支,永远可部署,受保护;- 功能分支命名
feat/-、fix/-,存活目标≤2天,超过3天CI会发提醒; - 大特性拆成多个小PR,用Feature Flag(后端用配置中心开关,前端用环境变量)控制可见性;
- 发布时从
main切release/1.24.x短期分支,只接受cherry-pick的修复,生命周期不超过2周; - Code Review强制:至少1人approve(核心模块2人),CI全绿才能合,禁止自己合自己的PR(管理员除外)。
关于分支保护,我们直接在GitHub上配了branch protection rule,关键参数:
- Require a pull request before merging:开启
- Require approvals:1(
src/main/java/com/xxx/core/**路径额外要求2人,用CODEOWNERS实现) - Dismiss stale pull request approvals when new commits are pushed:开启
- Require status checks to pass:
build-and-test、sonar-scan、lint三个必过 - Require branches to be up to date before merging:开启(这个后面踩坑了,见第五节)
- Require conversation resolution:开启
- Allow force pushes:关闭
四、核心实现:CI/CD配置与PR模板
4.1 GitHub Actions流水线
主流水线ci.yml,触发条件是PR到main以及main的push:
name: ci
on:
pull_request:
branches: [main]
push:
branches: [main]
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true
jobs:
build-and-test:
runs-on: [self-hosted, linux, x64]
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup JDK 17
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: '17'
cache: maven
- name: Backend build & test
run: mvn -B -ntp verify -Dspring.profiles.active=test
- name: Setup pnpm
uses: pnpm/action-setup@v2
with:
version: 8.6.12
- name: Frontend install & test
working-directory: web
run: |
pnpm install --frozen-lockfile
pnpm run lint
pnpm run test -- --run
sonar-scan:
needs: build-and-test
runs-on: [self-hosted, linux, x64]
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: SonarQube Scan
uses: sonarsource/sonarqube-scan-action@v2
env:
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
with:
args: >
-Dsonar.qualitygate.wait=true
-Dsonar.qualitygate.timeout=300
几个刻意的选择:concurrency按ref分组并cancel-in-progress,同一个PR连续push时自动取消旧运行,省runner;fetch-depth: 0是给SonarQube算增量覆盖率用的;qualitygate.wait=true让流水线等质量门禁结果,不通过直接红,避免"扫了但没人看"。
4.2 PR模板与CODEOWNERS
.github/pull_request_template.md:
## 变更说明
## 关联工单
Closes #
## 自测清单
- [ ] 本地 `mvn verify` 通过
- [ ] 涉及DB变更已附迁移脚本,且在预发验证
- [ ] 新增接口已更新 OpenAPI 文档
- [ ] 大特性已用 Feature Flag 包裹,默认关闭
## 风险与回滚
.github/CODEOWNERS:
/src/main/java/com/xxx/core/ @team-core @tech-lead
/web/src/components/ @team-frontend
/.github/ @devops
CODEOWNERS配合branch protection的"Require review from Code Owners",核心目录自动要求技术负责人审批,不用人工记。
4.3 Feature Flag 的最小实现
后端用一个配置中心的布尔开关,代码里这样用:
@Component
public class FeatureFlags {
private final ConfigService configService;
public FeatureFlags(ConfigService configService) {
this.configService = configService;
}
public boolean isEnabled(String key) {
return configService.getBoolean(key, false);
}
}
// 调用侧
if (featureFlags.isEnabled("new-billing-flow")) {
return newBillingService.calculate(order);
}
return legacyBillingService.calculate(order);
开关默认false,灰度时按租户ID百分比放量,这样大功能可以拆成十几个小PR持续合入main,而不是憋一个巨型分支。
五、踩坑与优化
坑1:Require branches to be up to date 造成的排队。开启这个选项后,PR必须基于最新main才能合。团队并行高的时候,一个PR刚update完,别人又合了一个,又得重新update+重跑CI,平均每个PR要多跑1.8次流水线。我们最后保留了这个选项(正确性优先),但配合concurrency取消旧运行 + 把CI压到6分钟内,实际体感可接受。如果你们CI超过15分钟,建议先别开这个。
坑2:SonarQube质量门禁卡在覆盖率上。初始门禁要求新代码覆盖率≥80%,结果前端组件测试覆盖不上,PR大面积红。调整为:后端新代码覆盖率≥70%、重复率≤3%、无Blocker问题;前端只卡ESLint error和Vitest通过,覆盖率不进门禁。门禁要卡"能改的",不然大家只会想办法绕过。
坑3:release分支的cherry-pick漏改。第一次用release/1.24.x时,修复只合了release没回合main,下个版本bug复现。解决办法是加了一条规则:release分支的修复PR合并后,必须在24小时内向main提一个backport PR,用label backport跟踪,每周五花10分钟对账。
优化:CI缓存。Maven和pnpm都开了缓存,配合self-hosted runner的本地.m2,后端构建从5分20秒降到2分10秒;前端pnpm install从90秒降到18秒。整条流水线P50从18分钟降到5分50秒。
六、效果数据
迁移后跑了完整两个季度,对比数据(取自GitHub Insights和Actions统计):
| 指标 | 迁移前 | 迁移后 |
|---|---|---|
| 功能分支平均存活 | 9.5天 | 1.7天 |
| 每周合并冲突次数 | 3.2 | 0.4 |
| PR平均首次Review等待 | 26小时 | 3.8小时 |
| CI流水线P50耗时 | 18分钟 | 5分50秒 |
| 发版前紧急修复次数(每版) | 2.3 | 0.5 |
main分支可部署率 |
约70% | 99.2% |
代价也有:前期花了约3人天做流程宣贯和工具配置,前两周大家频繁忘记开Feature Flag导致小回滚3次。但第三周之后就稳定了。
七、总结
回头看,这次改造真正起作用的不是某个工具,而是三件事的组合:短分支让集成问题暴露得早,强制Review + CODEOWNERS让质量责任落到人,CI门禁让"能合"和"能部署"变成同一件事。配置层面,如果你只想抄一样东西,我建议先抄branch protection那套参数和ci.yml的concurrency设置——投入最小,收益最直接。至于Trunk-Based,团队规模超过30人或者有强合规要求时,可能要重新评估release分支的粒度,别照搬。