> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# ADR：采用两层 GitHub ruleset

> **Status:** Superseded on 2026-07-17
>
> **Date:** 2026-07-17
>
> **Owner:** [`@retaintive/trusted-mergers`](https://github.com/orgs/retaintive/teams/trusted-mergers)

## ⚠️ 2026-07-17 后续决策

本 ADR 保留最初 rollout 的历史，不再描述当前 policy。团队确认所有需要人工 review 的 repo 都应 dismiss stale approvals，因此删除了重复的 `Production review gate`，改为：

- `Default branch baseline` 覆盖全部 repo。
- `Senior review gate` 覆盖除 `docs` 外的 repo，要求 `trusted-mergers` approval，并 dismiss stale approvals。
- `governance_tier` 保留给未来真正的 production-only deployment / release 要求。
- Org-wide PR template 已通过新的 public `.github` repo 上线；旧 automation history 已迁到 private、archived 的 `github-automation-private`。
- 当前规范以 [GitHub 组织治理与仓库基线](/engineering/github-governance.md) 为准。

## Context

2026-07-17 rollout 前 live audit 确认：Retaintive 有 12 个 active private repositories，当时 org-level ruleset 为 0。只有 3 个 active repo 有 active repo-level ruleset，另外 9 个 default branch 没有 ruleset 或 classic branch protection。现有 ruleset 的命名、approval、checks 和 bypass 也不一致。

如果继续只靠 repo-level 配置，新 repo 仍可能在创建后没有保护。另一方面，把同一 approval、CI context、CODEOWNERS 和 bot bypass 一次性强加给所有 repo，会让没有 reviewer/CI 的 repo 无法工作，或扩大 automation 权限。

## Considered options

### Option A：继续逐 repo 管理

优点是灵活，不改变现有结构。缺点是容易 drift，新 repo 默认没有保护，需要长期维护重复设置。

### Option B：一条严格 org ruleset 覆盖所有 repo

优点是集中。缺点是 approval、CI、owner 和 automation 需求并不统一；一个不存在的 required check 就能让 repo 无法 merge。

### Option C：两层 ruleset

第一层覆盖所有 repo 的最低安全底座；第二层只覆盖真正开发和上线的 repo。Repo-specific checks、CODEOWNERS mapping、environment 和 bot bypass 保留在 repo。

## Decision

选择 Option C。

1. 创建 org baseline，target 全部 repositories 的 `~DEFAULT_BRANCH`：PR required、0 approval、resolve review threads、block deletion、block force push。
2. 用 `governance_tier=production` 选择 Tier 2：1 approval、dismiss stale approvals；CODEOWNER approval 等 owner mapping 有效后再开启。
3. Required status checks 保持 repo-specific；未来可增加跨语言通用的 org required workflow。
4. Bypass 遵循最小范围：Tier 1 不设置 bypass；Tier 2 只允许 `trusted-mergers` 通过 PR bypass production approval gate。
5. Org rule 先 `evaluate`，复核 Rule Insights 后再单独批准 `active`。
6. 只有 org rule 已生效后，才清理重复 repo-level ruleset。

首批 Tier 2 repositories：`callytics-infrastructure`、`agent-plugins`、`market-lead-tracking`。`traceplane` 和 fork `botmux` 保持 baseline。

2026-07-17 implementation：

- `Default branch baseline`（ID `19114672`）已 active，target `~ALL` repositories 的 `~DEFAULT_BRANCH`，无 bypass。
- Required custom property `governance_tier` 已创建，default `baseline`，允许值为 `baseline`、`production`、`exception`。
- `Production review gate`（ID `19115958`）已 active，target `governance_tier=production`，要求 1 approval、dismiss stale approvals、resolve review threads；Team `trusted-mergers`（ID `18332203`）具有 `pull_request` mode bypass。
- Required checks 保持 repo-level：infra 沿用既有 CI gate；`agent-plugins` 要求 `validate`；`market-lead-tracking` 要求 `Detect Changes` 和 `CI Checks`。

## Consequences

正面影响：

- 新 repo 不再默认裸奔。
- `botmux` 使用 `master` 也能由 `~DEFAULT_BRANCH` 自动匹配。
- 低活动 repo 不因缺 reviewer 或 CI 被永久卡住。
- Production repo 的 review 和 CI 可以更严格，但不会扩大 bot 权限。
- `trusted-mergers` 可以在 production repo 中保留 PR 记录并 bypass approval gate；Tier 1 和 repo-level required checks 仍独立生效。
- Ruleset targeting 不再依赖长期维护 repo name 清单。

成本与限制：

- 必须持续维护 custom property values。
- `trusted-mergers` 目前只对 `callytics-infrastructure` 有显式 `write`，不能立即作为其他 repo 的有效 CODEOWNER。
- Required check name 变化必须与 repo ruleset 同步。
- Org ruleset 已 active；repo-level duplicate cleanup 完成前会短期双重覆盖。

## Explicitly not decided here

- 既有 repo-level bypass actors 是否继续保留。
- `botmux` 是否从 `master` rename 为 `main`。
- `callytics-infrastructure` disabled `Protection` ruleset 是否删除。
- 已归档 common 发布链留下的 `retaintive-schema-broadcaster` App 和 orphan workflow 何时清理。
- PR template 采用 managed copy、scaffolder 还是未来 public `.github` fallback。
- Team description 是否更新，或是否把 code ownership 与 trusted merge authority 拆成两个 teams。

这些项目在对应 change proposal 中展示 live evidence 后逐项批准。

## Revisit triggers

- GitHub plan 或 ruleset capability 变化。
- Repo 数量或团队规模显著变化。
- Required workflow 可以稳定替代多套 repo-specific policy check。
- Bypass 事件表明当前角色或范围过宽。
- Tier 2 repo 长期无法获得有效 reviewer/owner。

## Related

- [GitHub 组织治理与仓库基线](/engineering/github-governance.md)
- [GitHub organization rulesets](https://docs.github.com/en/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization)