必需状态检查与分支保护

配置分支保护规则、使主分支仅在必需 CI 检查通过后才能接受变更、阻坏或未审代码入库。

为什么

无分支保护、任何人可直推 main 或带失败检查合 PR——一次坏推可坏生产全员。必需状态检查把 CI 管道从建议变门控: 分支被保护、合按钮在所有必需检查通过前禁用、直推被拒。这是保持主分支常绿最有效控制。分支保护还强代码审查（必需批准）、新提交时清旧审、阻强推和分支删——合起使主分支为可审计可审查常可建历史线。成本近零（几分钟设）益处是防最常见坏主分支因。

何时使用

团队围绕仓库形成时（多一贡献者）——分支保护是基线控制永不应跳、应随团队成长收紧。

如何做

1. 列必过检查
   - lint、type-check、unit-test、integration-test、build
   - 仅要求可靠（非 flaky）且够快不阻团队的检查

2. 建分支保护规则（GitHub）
   - Settings > Branches > 分支保护规则 > 加规则
   - 分支名模式: main
   - 要求状态检查通过: 选 lint、type-check、unit-test、build
   - 要求合前分支最新（确保检查跑最新 main）
   - 勿要求仅信息检查（如 code-coverage-comment）

3. 要求 PR 审查
   - 必需批准审查: 1（关键仓 2）
   - 新提交时清旧批准
   - 要求 Code Owners 审查（用 CODEOWNERS 文件按路径所有权）

4. 限直推和强推
   - 限谁可推匹配分支（无人——所有变更经 PR）
   - 不允许强推
   - 不允许删

5. 验门控工作
   - 开失败必需检查的 PR——合按钮应禁用
   - 试直推 main——应被拒

示例

# .github/CODEOWNERS — 按路径审查所有权
*                           @team-lead
src/data/                   @data-team
src/components/             @frontend-team
astro/                      @frontend-team
.github/workflows/          @devops-team

# 分支保护（GitHub REST API）
curl -X PUT https://api.github.com/repos/$ORG/$REPO/branches/main/protection \
  -H "Authorization: token $TOKEN" \
  -d '{
    "required_status_checks": {
      "strict": true,
      "contexts": ["lint", "type-check", "unit-test", "build"]
    },
    "enforce_admins": true,
    "required_pull_request_reviews": {
      "required_approving_review_count": 1,
      "dismiss_stale_reviews": true
    },
    "restrictions": null,
    "allow_force_pushes": false
  }'

常见问题

⚠要求 flaky e2e 检查为必需检查——e2e 随机失败、合按钮禁用、开发者无法合正确 PR；团队失信门控开始绕。
⚠要求仅信息检查（如覆评论 bot）发评论但永不失败——它加必需检查列表噪、遮真正门控质量的检查。
⚠不对管理员强规则（enforce_admins: false）——管理员热修时直推 main 绕所有检查、引入门控本防的 bug。
⚠要求已不存在的检查（工作流被重命名或删）——GitHub 静默忽略缺失上下文、门控比预期弱、无人注意直到 bug 漏。

最佳实践

✓仅要求可靠快检查（lint、type-check、unit-test、build）——e2e 作非必需信息检查或移夜班、使 flaky 不阻合。
✓设 enforce_admins: true 使规则适用所有人——管理员仍可经 API 在记录的紧急中绕、但默认路径被门控。
✓用 CODEOWNERS 文件要求按路径审查——数据文件要 data-team 批准、基础设施文件要 devops 批准、自动路由审查到对专家。
✓季审必需检查列表——删已删工作流的检查、加新关键工作流检查、验门控仍匹配管道。