gh-bootstrap

gh-bootstrap

为 合并队列 + squash 合并 + 自动生成发布说明 模式进行一次性仓库配置。

这是一次性的仓库策略设置，与按任务执行的 GitHub 操作不同：这个仓库最初应如何配置？

配置内容

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

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

流程

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

进行任何更改前，先阅读路线图并与用户确认：

gh auth status
REPO="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
gh repo view "$REPO" --json nameWithOwner,visibility,defaultBranchRef,isPrivate
DEFAULT_BRANCH="$(gh repo view "$REPO" --json defaultBranchRef --jq '.defaultBranchRef.name')"
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?

# Legacy branch protection: a 404 with "Branch not protected" means none
# exists. Any other error must stop the protocol before rulesets are applied.
if legacy_protection=$(gh api "repos/$REPO/branches/$DEFAULT_BRANCH/protection" 2>&1); then
  echo "$legacy_protection"
elif [[ "$legacy_protection" == *"HTTP 404"* && "$legacy_protection" == *"Branch not protected"* ]]; then
  echo "No legacy branch protection on $DEFAULT_BRANCH."
else
  echo "::error::Could not check legacy branch protection: $legacy_protection" >&2
  exit 1
fi

询问用户：

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

合并队列可用性。 GitHub 支持公有组织所有的仓库，以及使用 GitHub Enterprise Cloud 的私有组织所有的仓库启用合并队列。个人所有的仓库（包括公有个人仓库）不符合条件。如果仓库和套餐不满足这些要求，请跳过 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 正文会成为提交正文，因此无需 GitHub 也能在 git log 中保留每项更改的理由。
• allow_auto_merge=true——合并队列按钮要能在无需人工盯守的情况下将 PR 加入队列，就必须启用此选项。

PATCH 操作具有幂等性：使用相同的值重新运行不会产生任何更改。

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

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

完整的载荷、资源模板以及创建与更新逻辑位于 references/ruleset.md 中——执行此步骤前请先阅读该文件。无队列版本以资源形式提供：

变体	资源	适用场景
main: PR + CI	assets/rulesets/main-pr-ci.json	个人或小型仓库。通过 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 变体，除非用户明确要求使用合并队列。它的结构更简单，也更适合日常个人开发。

幂等性： 列出规则集，查找目标为默认分支且名称与任一引导变体（main: PR + CI 或 main-protection）匹配的规则集。如果找到，则对其执行 GET，将其 rules、bypass_actors 和 conditions 与渲染后的载荷进行比较，显示差异，并在执行 PUT 前询问用户。如果用户切换变体，则复用该规则集的 id 执行 PUT，而不是新建第二个规则集；在停用或废弃先前变体的任何配置前，先征求用户同意。如果未找到，则通过 POST 新建。绝不要为默认分支创建重复的规则集。

4. 初始化发布说明配置

将 assets/release.yml 复制到 .github/release.yml。此文件用于 GitHub 自动生成发布说明（新建发布页面上的“Generate release notes”按钮，以及 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* 标签时触发
• 运行一个 verify 作业（contents: read、persist-credentials: false），该作业会检出仓库、确定默认分支，并在标签不是该分支的祖先时拒绝继续，以防未经审查的分支发布版本。将调用方的环境配置和质量门禁添加到此作业中。
• 运行一个 publish 作业（contents: write、needs: verify，不执行检出），调用 gh release create "$TAG" --generate-notes --verify-tag；如果标签包含 -，则添加 --prerelease

将 verify 与 publish 拆分，可以确保负责检出并审核仓库代码的作业永远不会持有 contents: write 权限。为确保供应链安全，Action SHA 已固定（而非使用浮动标签）。references/release.md 说明了固定了哪些 Action，以及新版本发布时如何更新它们。

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, reviews: ([.rules[] | select(.type=="pull_request") | .parameters.required_approving_review_count][0])}'
test -f .github/release.yml          && echo "release.yml present"
test -f .github/workflows/release.yml && echo "release workflow present"

摘要应说明：

• 做了哪些更改
• 哪些配置原本就正确（未做更改）
• 跳过了哪些内容（例如，免费套餐的私有仓库无法使用合并队列），以及跳过的原因

幂等规则

此技能旨在安全地重新运行于配置不完整的仓库：

• 仓库设置： PATCH 具有幂等性——重复应用相同的请求正文会返回无操作响应。
• 规则集： 按面向默认分支的任一引导变体名称查找。若找到，则比较差异，并在执行 PUT 前询问；切换变体时沿用其 ID。若不存在，则执行 POST。绝不重复创建。
• .github/release.yml： 覆盖前先比较差异；若内容不同，则先询问。
• 发布工作流： 同样先比较差异并询问。
• 绝不删除： 若先前的运行留下了某项产物（例如，新规则集之外还存在旧版经典分支保护规则），请告知用户，由用户决定。不要悄悄将其移除。

此技能不适用于

• 针对单项任务的 GitHub 操作（PR、议题、CI 状态、特定标签的发布）——不在范围内
• 本地 git 操作——不在范围内
• 提交前钩子——请使用 /prek
• 项目任务运行——不在范围内
• 设计 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进行分类，不会对直接提交进行分类。默认分支规则集会阻止直接推送，这正是发布说明能够完整生成的原因——这两项功能相辅相成。
• 只有确认符合 GitHub 使用条件时才使用合并队列。即使仓库是公开的，用户所有的仓库也无法使用此规则。请在仓库级别禁用合并提交。
• 如果此技能运行后，PR 页面上没有出现“准备就绪时合并”按钮，请再次确认 allow_auto_merge=true（仓库级别）和规则集的 merge_queue 规则都已生效。