Retaintive

    ADR：采用两层 GitHub ruleset

    Status: Superseded on 2026-07-17

    Date: 2026-07-17

    Owner: @retaintive/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 组织治理与仓库基线 为准。

    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。