safe-settings

safe-settings

接入 github/safe-settings——这是一款 Probot GitHub App，可从单个管理员仓库中的 YAML 文件同步仓库设置、分支保护、规则集、标签、团队、环境和协作者。

当组织希望以声明式方式大规模管理仓库策略，而不是逐个点击仓库的设置页面或运行一次性的 gh api 脚本时，请使用此技能。

何时选择 safe-settings，而非其他方案

情况	工具
单个仓库，一次性锁定策略	/gh-bootstrap（gh CLI，命令式）
多个仓库，需要集中策略并保持同步、检测偏差，并在 PR 上进行试运行	safe-settings（此技能）
针对具体任务的 GitHub 操作（PR、议题、CI 状态）	/gh

当多个仓库需要共享策略，且你希望通过 PR 和试运行门控来审核策略变更时，safe-settings 是合适的选择。对于单个仓库来说，它过于复杂。

运行此技能后，safe-settings 将配置的内容

• 仓库元数据（描述、主页、主题、可见性、默认分支、功能开关）
• 合并按钮设置（squash / merge / rebase、合并后删除、自动合并、更新分支）
• 安全开关（漏洞警报、自动安全修复）
• 分支保护（经典）和规则集（现代）
• 标签（通过 oldname 重命名、排除模式）
• 里程碑
• 协作者（按用户设置，使用 include / exclude 仓库列表）
• 团队（设置权限和可见性）
• 环境和部署规则
• 自定义属性
• 自动链接（Jira 风格的引用）

相同的 YAML 架构按组织 → 子组织 → 仓库分层，仓库级文件的优先级最高。

流程

1. 选择管理员仓库并确认范围

safe-settings 从组织中的单个管理员仓库读取配置。常见的两种布局如下：

管理员仓库	适用情况
<org>/.github	最快捷——组织已有此仓库，用于存放社区健康文件。设置 ADMIN_REPO=.github。
<org>/admin（专用仓库）	更适合大型组织，由专门的策略团队负责此仓库。设置 ADMIN_REPO=admin。

请与用户确认：

• 组织名称（如果是用户，使用 gh api user --jq '.login'；使用 gh api orgs/<org> 验证组织）
• 管理员仓库的选择（.github 是常见默认选项）
• 是否需要按子组织分组？（例如，按团队分组仓库，以应用不同策略）
• 部署方式是 GitHub Actions 定时任务（最简单）还是 托管的 Probot 应用（实时 Webhook）？

2. 搭建管理员仓库目录结构

管理员仓库中的标准目录结构：

<admin-repo>/
└── .github/
    ├── settings.yml              # org-level baseline — applies to all repos
    ├── suborgs/                  # optional — overrides for groups of repos
    │   └── <suborg-name>.yml
    └── repos/                    # optional — per-repo overrides
        └── <repo-name>.yml

从 assets/ 复制以下文件：

• assets/settings.yml → .github/settings.yml — 精简且有明确主张的组织基线（见下文）
• assets/suborg.yml → .github/suborgs/example.yml — 带注释的子组织模板
• assets/repo.yml → .github/repos/example.yml — 带注释的单仓库覆盖模板

assets/settings.yml 中的组织基线与 gh-bootstrap 默认设置一致：仅允许 squash 合并、使用 PR 标题作为提交主题、合并后删除分支，另外还包括启用合并队列和必需审核的默认分支规则集。有关完整的键目录和分层工作方式，请阅读 references/schema.md。

3. 选择部署方式

GitHub Actions 定时任务（建议作为起点）

• 设置成本最低——无需托管服务，也无需 Webhook 隧道
• 通过 npm run full-sync 每隔 N 小时同步一次
• 偏差会在定时任务间隔内修复，而非实时修复
• 将 assets/full-sync.yml 复制到 <admin-repo>/.github/workflows/safe-settings.yml

托管的 Probot 应用

• 实时响应 Webhook 事件（推送到 .github/settings.yml、创建仓库等）
• 需要托管服务（AWS Lambda、Docker、Heroku、k8s）和用于 Webhook 的公共 URL
• 确认定时任务方案可行，且组织需要即时同步后，再使用此方式
• 部署矩阵和环境变量参考请参阅 references/deploy.md

此技能默认使用 GHA 定时任务方案。只有用户提出要求时才切换到托管方案。

4. 创建 GitHub App

两种部署路径都需要安装 GitHub App。引导用户完成清单流程：

1. 在本地克隆 safe-settings：git clone https://github.com/github/safe-settings
2. cp .env.example .env，设置 GH_ORG=<org>
3. npm install && npm run dev
4. 打开显示的 URL →“Register a GitHub App” → 安装到组织
5. 保存以下值：
   • App ID → vars.SAFE_SETTINGS_APP_ID（仓库或组织变量）
   • Private key（下载的 .pem）→ secrets.SAFE_SETTINGS_PRIVATE_KEY（粘贴文件内容）
   • Client ID → vars.SAFE_SETTINGS_GITHUB_CLIENT_ID
   • Client secret → secrets.SAFE_SETTINGS_GITHUB_CLIENT_SECRET
   • Webhook secret → secrets.SAFE_SETTINGS_WEBHOOK_SECRET（仅托管的 Probot 需要）

GitHub App 需要对组织的仓库拥有管理员访问权限，才能管理设置。清单流程会自动申请正确的权限，不要手动编写权限列表。

5. 配置并测试

对于 GHA 路径：

# Set the variables and secrets on the admin repo (or org-wide).
gh variable set SAFE_SETTINGS_GH_ORG --body "<org>" --repo "<org>/<admin-repo>"
gh variable set SAFE_SETTINGS_APP_ID --body "<app-id>" --repo "<org>/<admin-repo>"
gh variable set SAFE_SETTINGS_GITHUB_CLIENT_ID --body "<client-id>" --repo "<org>/<admin-repo>"
gh secret set SAFE_SETTINGS_PRIVATE_KEY --body "$(cat private-key.pem)" --repo "<org>/<admin-repo>"
gh secret set SAFE_SETTINGS_GITHUB_CLIENT_SECRET --body "<secret>" --repo "<org>/<admin-repo>"

通过 workflow_dispatch 手动触发首次同步：

gh workflow run safe-settings.yml --repo "<org>/<admin-repo>"
gh run watch --repo "<org>/<admin-repo>"

检查运行输出。首次同步会记录它将应用的每项更改；后续运行除非发现配置偏差，否则不会输出日志。

6. 验证防护措施

safe-settings 自带两道安全防线，请确保都已配置：

• 对 PR 进行试运行 — 有人针对管理仓库发起 PR 并修改设置时，应用会发布状态检查，显示可能产生的更改。如果检查失败，不要合并。
• 验证器 — assets/settings.yml 包含用于仓库名称的 validator.pattern。请根据组织的命名规范自定义它，以便 safe-settings 拒绝将设置应用到名称不符合规范的仓库。

如需更严谨的配置，可在新的规则集中添加 enforcement: evaluate，先以影子模式测试，再切换为 active。参见 references/schema.md。

幂等性

safe-settings 采用协调式设计——对未更改的配置运行 full-sync 不会产生任何操作。此技能本身也是幂等的：

• 文件搭建：与 assets/ 模板进行差异比较，覆盖任何现有文件前先征求确认
• 变量/密钥：gh variable set 和 gh secret set 具有幂等性（以最后一次写入为准）；技能应在覆盖现有值前征求确认
• GHA 工作流文件：同样进行差异比较并征求确认

在仅部分配置完成的管理仓库上重新运行此技能，只应补齐缺失部分。

此技能不适用于

• 为没有所属组织的单个临时仓库设置策略——请使用 /gh-bootstrap
• 运行 PR / issue / CI 运维操作——请使用 /gh
• 本地 git 操作——请使用 /plate
• 在上游编写新的 safe-settings 规则——此技能使用已发布的应用，不负责开发它
• 从旧版 github/settings 应用迁移——safe-settings 是受支持的后继方案；此技能假定你是从头开始配置，或已不再使用 github/settings

注意事项

• 管理员仓库的路径很重要。默认情况下，safe-settings 会在 ADMIN_REPO 下的 .github/ 中查找配置；如果配置放在其他位置，请将 CONFIG_PATH 设置为该目录。
• GitHub App 需要具备 admin 权限，才能管理成员仓库的设置。用户安装的令牌不起作用——必须由安装在组织中的 App 执行。
• 通过 GHA 运行 full-sync 会在每次运行时触及组织中的每个仓库。对于超大型组织（>1000 个仓库），运行可能需要一小时，并消耗 Actions 分钟数——请使用托管的 Probot 路径，或按子组织限定范围。
• 同一个 YAML 键在不同层级可能表示不同含义。组织级别的 branches 会应用于每个仓库；仓库级别的 branches 只会覆盖该仓库。合并顺序采用深度合并——编写复杂的覆盖配置前，请先阅读 references/schema.md。
• 更改组织级别的 settings.yml 后，每个仓库都会在下次同步时应用该更改。除了在规则集上使用 enforcement: evaluate，没有“先应用到少数几个仓库”的开关。
• repos/<name>.yml 中的 force_create: true 会在仓库不存在时创建它。此功能强大且有风险——请谨慎使用。
• safe-settings 默认不会取消设置所有 API 字段。要移除标签，必须在 labels.exclude 中列出该标签；要移除协作者，通常需要删除对应条目并运行同步。在假设“从 YAML 中移除”就意味着“从 GitHub 中移除”之前，请先阅读架构说明。
• 合并队列是 rulesets 条目中的一条 merge_queue 规则——不是顶层开关。其结构与 /gh-bootstrap 的规则集负载相同，只是用 YAML 表示并在整个组织范围内应用。