#GitHub 组织治理与仓库基线

一句话：大家都可以修改，但修改不代表可以 merge。

Governance Owner: @retaintive/trusted-mergers

Status: Active

Last Verified: 2026-07-17

Scope: retaintive organization 的当前及未来 repositories

#先看这里：我们怎么管理 GitHub

#1. 所有成员都可以贡献

Org 的 Base permission 是 Write。所有成员都可以：

• 查看 repositories；在启用 Issues 的 repo 中查看 Issues。
• 在启用 Issues 的 repo 中创建、评论 Issue。
• 创建 feature branch 并提交修改。
• 发 Pull Request。

Write 代表可以参与开发，不代表可以绕过 default-branch rulesets，也不代表可以直接修改 main / master。

#2. 所有 default branch 都有统一底座

Default branch baseline 覆盖全部当前和未来 repositories，并通过 ~DEFAULT_BRANCH 自动兼容 main、master 或未来的 default branch rename：

• 必须走 PR。
• 必须 resolve review threads。
• 禁止 direct push。
• 禁止 force push。
• 禁止删除 default branch。
• 无 bypass。

Required CI 不放进这条 org baseline，因为每个 repo 的 check name 和 workflow 不同。

#3. Review 必须针对最新版

除 docs 外，default branch 还命中 Senior review gate：

• 当前要求 @retaintive/trusted-mergers 至少 1 个 approval。
• 只要 PR push 新 commit，旧 approval 就自动失效，必须重新 review 最新 diff。
• 这条规则不区分 production / non-production；review integrity 对所有需要人工审批的 repo 相同。

#4. trusted-mergers 是 Governance Team

当前成员是 Max 和 Peter。权限绑定 Team，不写死个人：

• Team 成员可以通过 PR bypass 人工 approval。
• 仍然必须开 PR。
• 仍然必须 resolve review threads。
• 仍然必须通过 required CI。
• 不能 direct push、force push 或删除 default branch。

trusted-mergers 已被分配 All-repository write，用于承担跨 repo reviewer 和 governance 职责。这个 repository role 本身不产生 bypass；bypass 来自 Senior review gate 中明确配置的 pull_request mode。

#5. Repo ownership 必须能扩展

当前小团队阶段，由 trusted-mergers 承担所有非 docs repo 的 senior review。未来如果有 10 个成员、每个人负责不同 repo，不增加 10 套 org ruleset，而使用 GitHub 原生的 Team + CODEOWNERS：

1. 按产品或技术责任建立 owner Team，例如 infra-owners、agent-platform-owners。
2. 给 owner Team 分配对应 repository 的 Write。
3. 在该 repo 的 .github/CODEOWNERS 中声明 owner Team。
4. Org review rule 统一要求 CODEOWNER approval。
5. 交接 ownership 时只改 Team membership；不改 org ruleset。
6. trusted-mergers 继续只承担 organization-wide governance bypass 和 backup review，不成为所有 repo 永久的日常 owner。

Repo owner 代表对该 repo 的 review 与维护负责，不代表 owner 自己的 PR 可以跳过 review；需要由同一 owner Team 的其他成员或 governance backup review。

#6. docs 是明确例外

docs 仍继承 Default branch baseline，但不命中 Senior review gate：

• 必须走 PR、resolve threads。
• 不能 direct push、force push 或删除 default branch。
• 不要求额外 approval，因此有 Write 的 Docs Team 成员可以自行 merge docs PR。
• Docs Team 当前包含 Max、Peter、Vivian，并显式拥有 retaintive/docs: Write。
• Docs Team 不获得其他 repo 的 review bypass。

#7. CI 属于 repository

• Required checks 由各 repo 自己配置。
• 没有稳定 CI 的 repo 不配置不存在的 required check。
• Human reviewer 没有 required-CI bypass。
• Bot/App 例外必须绑定具体 repo，并记录为什么普通 PR + CI 流程不能满足。

#8. Production 当前没有独立 review gate

所有需要人工 review 的 repo 都已经 dismiss stale approvals，因此不再维护重复的 Production review gate。

governance_tier custom property 继续保留，未来只用于真正的 production-only 要求，例如：

• Required deployment / Environment approval。
• Release gate。
• Production-only security 或 compliance workflow。

不能把“谁负责 review”与“是否 production”混成同一个属性。

#三层职责

Organization
├── 管全局默认值与最低安全底座
├── Base permission
├── Org rulesets
└── governance_tier

Teams + ownership mapping
├── 管谁负责什么
├── 哪些 repo 可以 Write
├── CODEOWNERS identity
└── 少量明确的 governance bypass

Repository
├── 管自己的 required CI
├── CODEOWNERS 文件
├── PR template
├── Environments / releases
└── 特殊 bot

这三层共同决定一个 PR 能否 merge：

能否 merge
= Organization baseline
+ Review ownership / bypass
+ Repository required CI
+ Environment / release requirements

#当前 live 配置

#Org rulesets

#Repo required checks

其他 repo 在没有可靠 CI 前只执行 org rulesets；不能要求一个不会出现的 check。

#Bypass 边界

#CODEOWNERS contract

当 repo 进入分布式 ownership 模型时，标准位置是 default branch 的 .github/CODEOWNERS：

* @retaintive/<owner-team>
/.github/ @retaintive/trusted-mergers

• Owner 使用 Team，不直接写个人账号。
• Team 必须对该 repo 有 Write 以上 access。
• Monorepo 可以用更具体的 path pattern 分配不同 owner Team。
• CODEOWNERS 负责“谁必须 review”，ruleset 负责“必须 review 才能 merge”。
• Ownership 变更优先修改 Team membership；只有目录职责变化才修改 CODEOWNERS。

参考 GitHub CODEOWNERS。

#PR template contract

Live status（verified 2026-07-17）： org-wide default PR template 已启用。Public retaintive/.github 在 default branch 提供 .github/pull_request_template.md；GitHub Community Profile API 已确认 docs 回落到该 default，而 callytics-infrastructure 继续使用自己的 repo-specific template。旧 automation history 保存在 private、archived 的 github-automation-private。

#PR description 的 source of truth

GitHub template files           = organization default、repo override 或 specialized contract
Contents + Community Profile API = 找到本次 PR 选择或默认生效的 contract
pr skill                        = 按真实 diff 智能填写并启用条件模块
fallback schema                 = 明确不存在 GitHub template 时兜底

GitHub template 是结构的 source of truth：repo 自己有 template 时优先使用 repo-specific override，否则继承 public .github 的 organization default。解析时先确定 PR 的 base/upstream repository，再区分两种情况：

• Multiple templates： 先用 Contents API 枚举 supported PULL_REQUEST_TEMPLATE/ directories 中的 Markdown files，优先遵循用户指定的 template 或 PR URL 的 template= parameter；存在多个合理候选时要求明确选择。Community Profile API 的单个 pull_request_template field 不能表示作者为本次 PR 选择了哪一份 specialized template。
• Default / single template： 没有选中 specialized template 时，再用 Community Profile API 解析 repo-specific override 或 public .github organization default。该 endpoint 不支持 fork；API 不可用时应从已确定的 base repository 直接读取 template，不能静默切到 head fork 或 fallback schema。

pr skill 保留选中 template 的核心 headings、说明和 checklist，再按实际 diff 启用 Screenshots、Root Cause、Architecture、migration、security 或 rollout 等条件模块。只有 GitHub lookup 明确证明没有 template 时，才使用 skill 内置的最小 fallback schema；具体解析流程由 skill 的 bundled reference 维护，本页不复制第二份实现步骤。

Organization default 的核心 contract 是 摘要、背景 / 为什么、改了什么、Validation、Risk / Rollout / Rollback 和 Reviewer guide；完整提示以 public .github/pull_request_template.md 为准。内容长度、段落、列表和图表数量服从改动复杂度，不设置固定句数。Repo-specific override 应保留这些核心 headings，并只增加该 repo 确实需要的技术检查；例如 callytics-infrastructure 保留 Lambda、CDK、observability 和 CHANGELOG.md validation。

#新 repo checklist

1. 默认创建为 private，default branch 使用 main。
2. 确认 Default branch baseline 和 Senior review gate 自动命中。
3. 指定 owner Team；进入分布式 ownership 模型后添加 .github/CODEOWNERS。
4. 默认继承 org-wide PR template；只有真实需要时才在 repo 的 .github/pull_request_template.md 做 override。
5. 只配置实际存在、名称稳定、会在目标 PR 上运行的 required checks。
6. 部署型 repo 再配置 Environments / release gate。
7. Bot/App bypass 必须单独 review scope；不授予人类 CI bypass。
8. 如果 repo 是像 docs 一样的 self-merge 例外，必须明确修改 review targeting，而不是给个人全局 bypass。

#Source of truth 与维护

1. GitHub live settings/API：实际 enforcement。
2. 本页：团队批准的 governance policy 和当前高层配置。
3. Private GitHub Admin Runbook：带时间戳的 ruleset ID、check inventory、复现命令和 drift audit。
4. Repo 自己的 workflow、CODEOWNERS、PR template 和 Environment：repo-specific truth。

更新触发：ruleset、Team ownership、bypass、required check、default branch 或新 repo lifecycle 发生变化时，同步更新本页；精确 inventory 只放 Admin Runbook，不在多个页面重复。