gh-setup

GitHub 设置

让 GitHub 成为可强制执行的外壳，围绕仓库现有的构建、验证、发布和部署约定运行。

范围与路线

从仓库指南以及负责所请求变更的文件和命令入手。在加载参考资料前，先选择下面的相关路线。

• 协作文件： 检查本地文件及适用的所有者默认设置。
• 工作流修正： 检查受影响的作业、其输入、权限、依赖项及必需检查行为。保留无关的交付策略。
• 设置或交付策略： 读取受影响的实时设置和相关参与方；如果要更改分支规则或必需检查，还要包括默认分支的写入方。在获准执行变更前，记录变更前状态和回滚路径。
• 发布或部署： 检查负责执行的脚本和操作手册，然后使用匹配的发布或部署路线。对于两者，都应发布一个不可变载荷，并部署该载荷，而不是重新构建。

本地修正不需要完整的实时策略清单。只有当依赖项或变更后的信任边界要求时，才扩大检查范围。 以仓库本地命令为准。如果所声称的交付面无法可靠地构建、验证、打包、观测或回滚，请报告缺失的前置条件，而不是将其隐藏在工作流 YAML 中。

共享约定

• 拉取请求以只读凭据执行不可信代码。
• 受信任的发布和部署作业只有在验证并确认输入或引用后，才加载凭据。
• 工作流权限默认为只读或 {}，并按作业扩大权限。
• 高信任级别的远程 Actions 使用经过审查的不可变固定版本，并提供更新路径。
• 环境机密和策略应与发布或部署的影响范围相匹配。
• 发布、推送、签名、晋级和部署的关键环节不可取消，并且能够协调恢复。
• 同一个经过验证的载荷贯穿构建、测试、发布和部署边界。
• 当矩阵、条件执行的任务或无操作路径会导致单个作业结果不稳定时，必需检查应使用稳定的最终结果。
• 必须回读任务更改的实时设置和下游状态；仅凭工作流成功并不能证明这些变更已生效。

添加或更改扫描、必需检查、计划任务或仓库安全功能时，请阅读安全基线。

添加工作流或更改代码执行、凭据、发布、签名或部署边界时，请阅读 Actions 安全。

配置触发器、运行器、并发、昂贵作业的选择方式或必需检查的运行时长时，请阅读运行器成本。 对于新的发布或部署机制，请从最接近的维护中实现入手。对于本地修正，只有在仓库代码未能解决实现问题时，才查阅示例。 应调整其约定，而不是照搬具体版本、身份或提供商细节。

仓库策略

更改合并方法、规则集、必需检查、签名提交、标签、Actions 策略、Environments、成本安全型组织安全基线、CodeQL 态势和仓库元数据时，请阅读仓库设置。

除非请求的更改明确涉及现有规则，否则请保留现有的审批、执行者、签名提交、标签和状态检查规则。运行检查与强制执行检查是两项独立操作。在要求通过拉取请求提交或要求通过某项检查之前，请盘点发布机器人、依赖项机器人、生成内容回写，以及仍会向默认分支写入内容的维护者。

默认情况下不要要求通过拉取请求提交。如果仓库策略允许直接更新，且默认分支 CI 默认运行与本地可复现的门禁相同的检查，则允许经过验证的快进推送。仅在需要合并前审查、需要处理不可信贡献、需要合并队列、需要在默认分支更新前通过检查，或所有者有明确策略要求时，才要求通过拉取请求提交。推送后运行的 CI 会在分支更新后检测回归，因此推送前应运行本地门禁，并持续监控 CI 直至完成。

协作文件

添加或调整拉取请求模板、问题表单、SECURITY.md、CONTRIBUTING.md 或共享社区默认配置时，请阅读模板。

• 仅当某项策略适用于每个仓库时，才优先采用所有者级别的公开默认配置。
• 模板应简短并以证据为导向；避免流于形式的检查清单。
• 公开安全指南必须提供可用的私密报告渠道。私有仓库应使用现有的私密维护者联系渠道。
• 添加或迁移 Dependabot 或 Renovate 前，请阅读依赖项更新。每个仓库只运行一个机器人。保持 Dependabot alerts 开启；使用 Renovate 时关闭 Dependabot security updates，因为 Renovate 会自行创建漏洞拉取请求。

发布与部署路径

发布工作使用：

• 发布工作流，了解信任、发布、签名回写、不可变发布、恢复和完成证明
• 发布目标，了解 npm、Swift/CocoaPods、Go、Rust、GitHub Actions、Homebrew 和单体仓库
• 仅在选用该工具时使用 semantic-release
• 仅在发生具体故障或持久状态不一致后使用发布故障排查

部署工作使用：

• 部署工作流，了解触发条件、通道检测、经过验证的有效负载、并发控制和监控交接
• 更改目标选择、保护、OIDC 或提供商边界时，请参阅 Environments
• 更改密钥所有权或日志记录时，请参阅凭据
• 仅在发生具体故障后使用部署故障排查

验证并完成

工作流发生更改时，运行仓库门禁以及 actionlint 和 zizmor。当实时交付属于工作范围且已获授权时，执行范围最小且安全的验证。仅修改工作流并不代表获准发布或部署。若无法进行实时验证，请继续已获授权的本地工作，并报告这一缺口。试运行和静态检查无法证明不可变发布、签名回写、注册表或 tap 一致性、部署、监控或回滚已成功。

获准进行实时更改后，请回读范围内的每项设置、Environment、规则、发布、注册表、标签、部署或下游指针。发生部分失败时，请先协调持久状态再重试；切勿仅为使工作流变绿而创建新版本或修改不可变发布。

输出

files: changed GitHub and documentation surfaces
settings: live changes and readback, or not checked
delivery: target and immutable payload boundary
evidence: local, workflow, and live proof actually exercised
risks: remaining authority, recovery, or downstream gaps