4. 代码仓库与分支策略：GitFlow、Trunk-Based Development、保护分支与合并请求规范

在 K8s 平台发布流水线中，代码仓库的组织方式与分支策略直接决定了变更的流转速度、安全审计粒度以及回滚效率。错误的策略会导致合并冲突频繁、发布窗口延长、甚至生产事故扩散。本章从三种主流分支模型出发，结合保护分支与合并请求（MR/PR）规范，给出适用于 Helm Chart 与平台配置的推荐实践。

4.1 三种分支模型对比

4.2 分支策略与 Helm Chart 版本映射

Helm Chart 的版本号（Chart.yaml 中的 version）必须与分支策略对齐，否则会导致发布流水线无法追溯。下表给出推荐映射关系：

4.3 保护分支规则设计

保护分支是流水线安全的最后一道防线。以下规则适用于 Helm Chart 仓库与平台配置仓库：

• 禁止直接推送：main、release/*、hotfix/* 分支禁止任何人直接 push，所有变更必须通过合并请求。
• 线性历史要求：启用 "Require linear history"，禁止 merge commit，只允许 squash merge 或 rebase merge，确保 Git 历史可追溯。
• 状态检查强制：必须通过以下检查才能合并：
  • Helm lint 通过
  • Helm template 渲染无错误
  • Kubeconform / kubeval 校验通过
  • 单元测试（如 unittest plugin）通过
  • 至少 1 名 Code Owner 批准
• 过时审批丢弃：当新提交推送后，自动丢弃之前的审批，要求重新 review。
• 分支过期策略：超过 7 天未更新的 feature 分支自动标记为 stale，并触发提醒。

4.4 合并请求规范与准入核验清单

合并请求（MR/PR）是 Helm Chart 变更进入主干的唯一入口。以下规范必须作为流水线准入核验的一部分：

1. 标题格式：[类型] 简短描述，类型包括 feat、fix、chore、docs、refactor。
2. 变更范围：每个 MR 只包含一个逻辑变更。禁止混合 Chart 版本升级与 values 参数修改。
3. 必须包含：
   • 变更说明（What & Why）
   • Helm 渲染结果截图或 diff 链接
   • 影响范围标注（namespace、集群、环境）
4. 禁止项：
   • 禁止在 MR 中修改 .gitignore、.helmignore 等无关文件
   • 禁止提交 secrets.yaml 或包含明文凭据的 values 文件
   • 禁止提交大于 10MB 的二进制文件

# .gitlab-ci.yml 片段
check-mr-convention:
  stage: .pre
  script:
    - |
      # 检查 MR 标题格式
      if ! echo "$CI_MERGE_REQUEST_TITLE" | grep -qE '^\[(feat|fix|chore|docs|refactor)\]\s.+'; then
        echo "MR 标题不符合规范"
        exit 1
      fi
    - |
      # 检查是否包含 secrets 文件
      if git diff --name-only $CI_MERGE_REQUEST_DIFF_BASE_SHA...$CI_COMMIT_SHA | grep -i 'secret\|password\|'; then
        echo "MR 包含敏感文件"
        exit 1
      fi
    - |
      # 检查 Chart 版本是否已变更（仅 main 分支允许）
      if [ "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" = "main" ]; then
        if ! git diff $CI_MERGE_REQUEST_DIFF_BASE_SHA...$CI_COMMIT_SHA -- Chart.yaml | grep -q '+version:'; then
          echo "合并到 main 必须提升 Chart 版本"
          exit 1
        fi
      fi

4.5 分支策略与 Helm 发布流水线集成

下图展示 Trunk-Based Development 模式下，分支策略如何与 Helm 发布流水线各阶段联动：

4.6 分支清理与生命周期管理

长期存在的分支会导致流水线资源浪费和合并冲突累积。建议实施以下清理策略：

• 自动删除源分支：MR 合并后自动删除 feature 分支。
• Stale 分支标记：超过 14 天未活动的分支自动标记，并发送通知给最后提交者。
• 归档策略：超过 30 天未活动的分支自动归档到 archive/ 命名空间，避免干扰活跃分支列表。
• 保护分支例外：release/* 和 hotfix/* 分支不受自动清理规则影响，但需设置过期提醒。

# .github/workflows/cleanup-stale-branches.yml
name: Cleanup Stale Branches
on:
  schedule:
    - cron: '0 6 * * 1'  # 每周一早上6点
jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Delete stale branches
        run: |
          # 删除超过14天未活动的 feature 分支
          for branch in $(git branch -r --merged origin/main | grep 'origin/feature/' | sed 's/origin\///'); do
            last_commit=$(git log -1 --format=%ct origin/$branch)
            now=$(date +%s)
            age=$(( (now - last_commit) / 86400 ))
            if [ $age -gt 14 ]; then
              echo "Deleting stale branch: $branch (age: $age days)"
              git push origin --delete $branch
            fi
          done

4.7 分支策略与 Helm 准入核验的联动

分支策略不是孤立存在的，它必须与 Helm 准入核验机制深度绑定。以下是推荐的联动规则：