一、问题背景:我们为什么不得不重做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

我们评估了三个方向:

  1. 继续用Git Flow,加规则约束:比如强制分支存活不超过5天。但Git Flow的双长期分支结构天然鼓励"攒着再合",靠纪律对抗结构,成本太高。
  2. GitHub Flow:单main分支 + 功能分支 + PR。方向对了,但缺Release分支的处理,我们还有对老版本打补丁的需求。
  3. 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分支的粒度,别照搬。