GitHub Actions 分支保护与 Rulesets：必需检查、CODEOWNERS 与仓库治理

Branch protection rules（经典）
  - 每个分支一条规则，用 pattern 匹配（如 main、release/*）
  - 配置分散在 Settings → Branches
  - 只有 "apply to administrators" 一个总开关决定 admin 是否豁免
  - 没有 evaluate 模式，只能全量生效
  - 不支持组织级统一下发

Rulesets（新版，推荐）
  - 一条 ruleset 可以覆盖多个分支或标签
  - 支持 enforcement 三态：active / evaluate / disabled
  - 支持 bypass actors 精细授权（团队、角色、应用、Deploy key）
  - 支持组织级 ruleset，向下级仓库下发
  - 可导出为 JSON，天然适合 IaC 管理

第 1 步：读取现有经典规则，确认目标分支列表
第 2 步：在 Rulesets 中重建同等规则，enforcement 设为 evaluate
第 3 步：观察 1~2 周，确认 PR 没有被意外拦截
第 4 步：enforcement 切换为 active
第 5 步：删除 Settings → Branches 中的经典规则

{
  "name": "protect-main",
  "target": "branch",
  "enforcement": "active",
  "conditions": {
    "ref_name": {
      "include": ["~DEFAULT_BRANCH", "refs/heads/release/*"],
      "exclude": []
    }
  },
  "rules": [
    { "type": "deletion" },
    { "type": "non_fast_forward" },
    { "type": "required_linear_history" },
    { "type": "required_signatures" },
    {
      "type": "pull_request",
      "parameters": {
        "required_approving_review_count": 2,
        "dismiss_stale_reviews_on_push": true,
        "require_code_owner_review": true,
        "require_last_push_approval": true,
        "required_review_thread_resolution": true
      }
    },
    {
      "type": "required_status_checks",
      "parameters": {
        "strict_required_status_checks_policy": true,
        "required_status_checks": [
          { "context": "test (3.11)" },
          { "context": "lint" }
        ]
      }
    }
  ]
}

deletion                    禁止删除匹配的分支
non_fast_forward            禁止强推（force push），即禁止非快进更新
required_linear_history     禁止 merge commit，只允许 squash 或 rebase
required_signatures         所有提交必须签名（GPG / SSH / S/MIME）
pull_request                必需 PR 审查，附带一批子参数
required_status_checks      必需状态检查，CI 的 job 名要与之对齐
creation                    限制分支创建（限制谁/哪种命名能新建）
update                      限制对分支的更新（一般与 bypass 配合）
required_deployments        要求指定 environment 先部署成功
workflows                   要求指定工作流在特定事件下必须成功

# .github/workflows/ci.yml
name: CI

jobs:
  build-and-test:              # job id
    name: Build and Test       # ← 这个才是 context
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

jobs:
  test:
    name: test (${{ matrix.python-version }})
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12"]

on:
  pull_request:
    paths:
      - "src/**"

方案 A（推荐）：去掉 workflow 级 paths 过滤，改为在 job 内做条件判断
方案 B：额外配置一个同名的 "always pass" job，用 if 判断后直接成功
方案 C：把该检查从必需列表中移除（会削弱保护，不推荐）

jobs:
  docs-check:
    name: docs-check
    runs-on: ubuntu-latest
    steps:
      - id: changed
        uses: tj-actions/changed-files@v44
        with:
          files: docs/**
      - name: Run or skip
        if: steps.changed.outputs.any_changed == 'true'
        run: npm run lint:docs

{
  "bypass_actors": [
    {
      "actor_id": 5,
      "actor_type": "RepositoryRole",
      "bypass_mode": "always"
    },
    {
      "actor_id": 123456,
      "actor_type": "Team",
      "bypass_mode": "pull_request"
    },
    {
      "actor_id": null,
      "actor_type": "DeployKey",
      "bypass_mode": "always"
    }
  ]
}

always        完全绕过，可直接 push，不受任何规则限制
pull_request  只能绕过「必需 PR 审查」，仍受状态检查等其它规则约束

active     规则生效，违规操作被拦截
evaluate   规则不拦截，只记录「本应被拦截」的事件，用于灰度验证
disabled   规则完全不生效，但配置保留

{
  "name": "org-baseline",
  "target": "branch",
  "enforcement": "active",
  "conditions": {
    "repository_name": {
      "include": ["*"],
      "exclude": ["sandbox-*", "docs-*"]
    }
  }
}

# 列出仓库的全部 rulesets
gh api repos/OWNER/REPO/rulesets

# 查看某条 ruleset 的完整定义
gh api repos/OWNER/REPO/rulesets/RULESET_ID

# 创建（从 JSON 文件导入）
gh api repos/OWNER/REPO/rulesets \
  --method POST \
  --input ruleset.json

# 更新
gh api repos/OWNER/REPO/rulesets/RULESET_ID \
  --method PUT \
  --input ruleset.json

# 导出为文件做备份
gh api repos/OWNER/REPO/rulesets/RULESET_ID > backup.json

name: Sync Rulesets

on:
  push:
    branches: [main]
    paths:
      - ".github/rulesets/**"

permissions:
  contents: read
  administration: write

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Apply rulesets
        env:
          GH_TOKEN: ${{ secrets.RULESET_ADMIN_TOKEN }}
        run: |
          for f in .github/rulesets/*.json; do
            echo "Applying $f"
            gh api repos/${{ github.repository }}/rulesets \
              --method POST --input "$f" || \
            gh api repos/${{ github.repository }}/rulesets \
              --method PUT --input "$f"
          done

resource "github_repository_ruleset" "main" {
  name        = "protect-main"
  repository  = github_repository.app.name
  target      = "branch"
  enforcement = "active"

  conditions {
    ref_name {
      include = ["~DEFAULT_BRANCH"]
      exclude = []
    }
  }

  rules {
    deletion                = true
    non_fast_forward        = true
    required_linear_history = true

    pull_request {
      required_approving_review_count   = 2
      dismiss_stale_reviews_on_push     = true
      require_code_owner_review         = true
      require_last_push_approval        = true
      required_review_thread_resolution = true
    }

    required_status_checks {
      strict_required_status_checks_policy = true
      required_check {
        context = "test (3.11)"
      }
      required_check {
        context = "lint"
      }
    }
  }
}

.github/CODEOWNERS     ← 推荐，随代码一起版本化
CODEOWNERS             ← 仓库根目录
docs/CODEOWNERS        ← 已废弃，兼容保留

# 注释行
*                       @org/platform-team          # 兜底：所有文件
/docs/                  @org/docs-team              # 目录下全部文件
*.js                    @org/frontend               # 按扩展名
/src/api/*.ts           @alice @bob                 # 多个人
apps/web/               @org/web-team
!apps/web/generated/                                # 取反需配合前面的规则

关键规则：
  - 最后匹配的规则优先（顺序很重要，兜底的 * 放最前面）
  - 目录写法 /docs/ 只匹配该目录，docs/ 会匹配任意层级
  - 团队必须对该仓库有 write 权限，否则 CODEOWNERS 不生效
  - 只有开启 require_code_owner_review，CODEOWNERS 才会成为合并门禁

{
  "name": "protect-tags",
  "target": "tag",
  "enforcement": "active",
  "conditions": {
    "ref_name": {
      "include": ["refs/tags/v*"],
      "exclude": []
    }
  },
  "rules": [
    { "type": "deletion" },
    { "type": "update" },
    { "type": "creation" }
  ]
}

on:
  merge_group:      # 合并队列会触发这个事件

要点：
  - workflow 必须监听 merge_group 事件，否则队列里的检查不会跑
  - 必需检查的 context 在队列中与 PR 中保持一致
  - strict 模式与合并队列二选一即可，同时开启会互相拖慢
  - 合并队列能消除「两个 PR 各自通过、合并后互相破坏」的竞态

排查顺序：
  1. context 拼写是否与 job 的 name 完全一致（含空格、大小写、括号）
  2. workflow 是否被 paths / paths-ignore 过滤掉，导致未触发
  3. workflow 是否只在特定分支触发，而目标分支不在其中
  4. 检查是否来自第三方 App（如 Codecov），其 context 与 job 名不同
  5. 是否有 job 因 if 条件被跳过，导致状态为 neutral
  6. workflow 文件是否有 YAML 语法错误，导致整个 workflow 未加载

原因：bypass actors 中存在 RepositoryRole(admin) 且 bypass_mode 为 always
修复：
  - 将 admin 的 bypass_mode 改为 pull_request
  - 或直接移除 RepositoryRole 的 bypass 条目
  - 注意经典规则里的 "Do not allow bypassing the above settings" 也要勾选

  - 组织级 ruleset 与仓库级叠加，被更严的一方拦住
  - enforcement 仍是 evaluate 或 disabled
  - conditions 的 ref_name 写的是 refs/heads/main 而非 ~DEFAULT_BRANCH
  - 规则目标 target 写成了 branch 但想保护的是 tag
  - 分支名 pattern 用了 glob 但写法不符合 GitHub 语法

概念                     关键值
--------------------------------------------------------
必需检查 context         与 job 的 name 字段逐字一致
matrix check 名          name: test (${{ matrix.x }}) 会展开
强制最新                  strict_required_status_checks_policy
线性历史                  required_linear_history
提交签名                  required_signatures
CODEOWNERS 位置           .github/CODEOWNERS 优先
CODEOWNERS 生效开关        require_code_owner_review
绕过模式                  always / pull_request
生效状态                  active / evaluate / disabled
管理权限                  administration: write
合并队列事件               merge_group
默认分支写法               ~DEFAULT_BRANCH