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

# GitHub 组织治理与仓库基线

> **一句话：大家都可以修改，但修改不代表可以 merge。**
>
> **Governance Owner:** [`@retaintive/trusted-mergers`](https://github.com/orgs/retaintive/teams/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”混成同一个属性。

## 三层职责

```text
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：

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

| 层级           | 只负责什么                                                       | 不应该放什么                       |
| ------------ | ----------------------------------------------------------- | ---------------------------- |
| Organization | 所有新旧 repo 都必须遵守的最低保护与 organization-wide policy              | 某个 repo 独有的 CI context 或 bot |
| Teams        | 人员分组、repository ownership、review responsibility、少量治理 bypass | CI job name、deployment 实现    |
| Repository   | CI、CODEOWNERS、PR template、Environment、release 与 App 特例      | 重复复制 org baseline            |

## 当前 live 配置

### Org rulesets

| Ruleset                   | Target                                   | Rules                                                       | Bypass                    |
| ------------------------- | ---------------------------------------- | ----------------------------------------------------------- | ------------------------- |
| `Default branch baseline` | `~ALL` repositories + `~DEFAULT_BRANCH`  | PR required、resolve threads、block deletion、block force push | 无                         |
| `Senior review gate`      | `~ALL` except `docs` + `~DEFAULT_BRANCH` | `trusted-mergers` 1 approval、dismiss stale approvals        | `trusted-mergers`，PR-only |

### Repo required checks

| Repository                 | Required checks                                  | Human bypass |
| -------------------------- | ------------------------------------------------ | ------------ |
| `callytics-infrastructure` | `CI Checks & Lambda Builds`、`Validation Summary` | 无            |
| `agent-plugins`            | `validate`                                       | 无            |
| `market-lead-tracking`     | `Detect Changes`、`CI Checks`                     | 无            |

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

### Bypass 边界

| Rule                                          | `trusted-mergers` | 普通成员      | Bot/App                  |
| --------------------------------------------- | ----------------- | --------- | ------------------------ |
| Baseline PR / threads / deletion / force-push | 不能 bypass         | 不能 bypass | 默认不能 bypass              |
| Senior human approval                         | PR-only bypass    | 不能 bypass | 默认不能 bypass              |
| Repo required CI                              | 不能 bypass         | 不能 bypass | 只有单独批准的 repo-specific 例外 |

## CODEOWNERS contract

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

```text
* @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](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)。

## PR template contract

> **Live status（verified 2026-07-17）：** org-wide default PR template 已启用。Public [`retaintive/.github`](https://github.com/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

```text
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`](https://github.com/retaintive/.github/blob/main/.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](https://github.com/retaintive/docs/blob/main/docs/team-ops/github-admin-guide.md)：带时间戳的 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，不在多个页面重复。