gh-bootstrap

gh-bootstrap

用于一次性配置仓库，采用 合并队列 + Squash 合并 + 自动生成发布说明 模式。

它与 /gh（按任务执行 GitHub 操作）并列，回答的是另一个问题：这个仓库一开始应该如何配置？

配置内容

事项	结果	端点
仓库合并默认设置	仅允许 Squash 合并；PR 标题 → 提交主题；合并后删除分支	PATCH /repos/{owner}/{repo}
默认分支保护	规则集包含合并队列、必需检查、禁止强制推送和删除	POST /repos/{owner}/{repo}/rulesets
发布说明	.github/release.yml，按 PR 标签划分类别	文件提交
发布工作流（可选）	仅在 main 上推送标签时运行 gh release create --generate-notes	文件提交

所有策略端点（仓库设置、规则集、分支保护）都通过 gh CLI 执行——JSON 端点使用 gh api，有专用子命令时则使用 gh repo/gh release。该技能会直接将文件（.github/release.yml 和可选的发布工作流）写入工作树。

流程

1. 确认范围并检查当前状态

进行任何更改前，先查看跑道并与用户确认：

gh auth status
gh repo view --json nameWithOwner,visibility,defaultBranchRef,isPrivate
gh api "repos/$REPO" --jq '{
  squash:   .allow_squash_merge,
  merge:    .allow_merge_commit,
  rebase:   .allow_rebase_merge,
  delete:   .delete_branch_on_merge,
  title:    .squash_merge_commit_title,
  body:     .squash_merge_commit_message,
  auto:     .allow_auto_merge
}'
gh api "repos/$REPO/rulesets"                                # any rulesets already?
gh api "repos/$REPO/branches/main/protection" 2>/dev/null    # legacy branch protection?

询问用户：

• 默认分支（假设为仓库的 defaultBranchRef，通常是 main）
• 必需状态检查的名称（例如 validate / validate skills、ci、test）——这些必须与 CI 输出的名称一致
• 必需的批准审核数量（默认为 1；个人仓库设为 0 也可以）
• 是否要搭建可选的发布工作流，还是只创建 .github/release.yml

合并队列可用性。 GitHub Free 仅支持在公开仓库中使用合并队列。私有仓库需要 Team 或 Enterprise。如果仓库是 Free 计划下的私有仓库，请跳过 merge_queue 规则并告知用户；其他设置仍然适用，其余保护规则集也会照常安装。

2. 设置仓库合并默认值

通过一次 PATCH 原子性地设置所有合并按钮选项：

gh api -X PATCH "repos/$REPO" \
  -F allow_squash_merge=true \
  -F allow_merge_commit=false \
  -F allow_rebase_merge=false \
  -F allow_auto_merge=true \
  -F delete_branch_on_merge=true \
  -F squash_merge_commit_title=PR_TITLE \
  -F squash_merge_commit_message=PR_BODY

各标志的作用：

• allow_squash_merge=true、allow_merge_commit=false、allow_rebase_merge=false——合并 PR 时只有 Squash 按钮，因此 main 的历史记录中，每个已合并的 PR 都只对应一个提交。
• delete_branch_on_merge=true——分支内容已折叠为一个提交，分支自然也不再需要；保留引用没有意义。
• squash_merge_commit_title=PR_TITLE——Squash 提交的主题行原样使用 PR 标题。这样，main 上的 git log --oneline 就会显示已合并 PR 的列表。
• squash_merge_commit_message=PR_BODY——PR 正文会成为提交正文，因此每次更改的理由都会保留在 git log 中，无需依赖 GitHub。
• allow_auto_merge=true——这是合并队列按钮将 PR 加入队列、无需人工看管的必要设置。

PATCH 具有幂等性：使用相同的值重新运行时不会产生任何变化。

3. 使用规则集锁定默认分支

规则集是 GitHub 对分支保护的现代替代方案——它们将合并队列作为一等规则来支持，可与组织规则集干净地叠加，并且可通过 API 查询。默认使用规则集；只有用户明确要求时才回退到传统分支保护（例如，用户固定使用较旧版本的 GHE）。

完整负载、资源模板以及创建与更新逻辑位于 references/ruleset.md 中——执行此步骤前请先阅读该文件。随附资源中包含两个规范变体：

变体	资源	适用情形
main: PR + CI	assets/rulesets/main-pr-ci.json	个人或小型仓库。仅允许 Squash 合并，使用 allowed_merge_methods: ["squash"]；所需审核数为 0；单个 CI 检查；不使用合并队列。
main-protection（队列）	references/ruleset.md 中的内联 JSON	有并发 PR 处理需求的团队仓库。添加 merge_queue 规则、至少 1 次审核以及一组 CI 检查。

两个变体具有相同的结构：

• target: "branch"，conditions.ref_name.include: ["~DEFAULT_BRANCH"]
• enforcement: "active"
• 规则：deletion、non_fast_forward、pull_request、required_status_checks

除非用户明确要求使用合并队列，否则默认采用 main: PR + CI 变体。它的结构更简单，也更适合日常个人工作。

**幂等性：**先列出规则集，查找名称一致的规则集。如果存在，则对同一 id 执行 PUT；如果不存在，则执行 POST 创建一个。绝不重复创建。

4. 配置发布说明

将 assets/release.yml 复制到 .github/release.yml。GitHub 的自动生成发布说明功能会使用此文件（即“新建发布”页面上的“生成发布说明”按钮，以及 gh release create --generate-notes）。该文件会根据 PR 标签，将合并的 PR 分入 Breaking / Features / Fixes / Docs / Internal / Other 类别。

如果 .github/release.yml 已存在，请将其与模板进行比较，并在覆盖前询问。不要悄悄覆盖用户现有的类别。

5. 配置发布工作流（可选）

如果用户选择启用，请将 assets/release-workflow.yml 复制到 .github/workflows/release.yml。此工作流：

• 在推送 v* 标签时触发
• 如果标签不是 origin/main 的祖先，则拒绝发布——这样未经审核的分支就无法发布版本
• 调用 gh release create "$TAG" --generate-notes，根据 .github/release.yml 中的类别生成正文

为保障供应链安全，操作使用固定的 SHA（而非浮动标签）。references/release.md 说明了固定了哪些操作，以及新版本发布时如何更新它们。

6. 验证并报告

重新读取所有内容，并向用户打印一张简短的摘要表。未从 API 读取操作后的状态前，不要声称已成功。

gh api "repos/$REPO" --jq '{
  squash: .allow_squash_merge, merge: .allow_merge_commit, rebase: .allow_rebase_merge,
  delete: .delete_branch_on_merge, title: .squash_merge_commit_title, body: .squash_merge_commit_message
}'
gh api "repos/$REPO/rulesets" --jq '.[] | {id, name, enforcement, target}'
test -f .github/release.yml          && echo "release.yml present"
test -f .github/workflows/release.yml && echo "release workflow present"

摘要应说明：

• 更改了什么
• 哪些内容已经正确（未执行更改）
• 跳过了什么（例如，免费版私有仓库中未启用合并队列）以及原因

幂等性规则

此技能旨在安全地应用于已部分配置的仓库，也可以安全地重复运行：

• 仓库设置：PATCH 具有幂等性——重新应用相同的请求正文会得到无操作的响应。
• **规则集：**按名称查找；存在时执行 PUT，不存在时执行 POST。绝不重复创建。
• **.github/release.yml：**覆盖前进行比较；如果内容不同，则先询问。
• **发布工作流：**同样先进行比较并询问。
• **绝不删除：**如果先前的运行留下了某项产物（例如，新规则集旁边还存在旧版传统分支保护规则），请告知用户，由用户决定。不要悄悄移除。

此技能不适用于

• 针对单个任务的 GitHub 操作（PR、问题、CI 状态、特定标签的发布）——使用 /gh
• 本地 Git 操作——使用 /plate
• 提交前钩子——使用 /prek
• 项目任务运行——使用 /justfile
• 设计 CI 流水线——不在此范围内；如果有人提出要求，此技能只会编写一个特定的发布工作流
• 为 CI 尚未生成状态检查名称的仓库补录这些名称——此技能会告诉你要使用哪些名称，需由你将其接入 CI

注意事项

• 必需的状态检查名称必须与 CI 在 Checks API 中生成的名称完全一致。PR 通过检查后，运行 gh api repos/$REPO/commits/<sha>/check-runs --jq '.check_runs[].name' 查看实际名称——不易察觉的拼写错误会导致合并门禁失效。
• 使用 squash_merge_commit_message=PR_BODY 的压缩合并会将完整的 PR 描述放入提交正文。建议保持 PR 正文整洁；杂乱的内容会永久留在提交历史中。
• 仓库（或适用于组织范围的组织级规则集）需要管理员权限才能使用规则集。只有 push/PR 权限范围的令牌会在此处收到 403 错误。
• 自动生成的发布说明只会归类已合并的 PR，不会归类直接提交。默认分支规则集会阻止直接推送，这正是发布说明能够完整生成的原因——这两项功能相辅相成。
• 合并队列与 required_linear_history 可以正常配合（压缩合并始终只会生成一个提交），但与 allow_merge_commit=true 同时使用则不行——请在仓库级别禁用合并提交。
• 如果此技能运行后，PR 页面中没有显示“准备就绪时合并”按钮，请再次确认 allow_auto_merge=true（仓库级别）和规则集的 merge_queue 规则都已生效。