Back to Details

gh-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GitHub Setup

GitHub 配置

Make GitHub the enforceable shell around the repository's existing build, verification, release, and deployment contracts.
让GitHub成为围绕仓库现有构建、验证、发布及部署约定的可强制执行框架。

Inspect and Classify

检查与分类

Before changing files or live settings:
  1. Read repository guidance, manifests, verification commands, release or deploy scripts, 
    .github/
    , contributor/security docs, and any repository-owned delivery runbook.
  2. Read live GitHub state: default branch, merge methods, effective branch rules, Actions policy, Environments, protected tags, security settings, and every human or automated default-branch writer affected by the change.
  3. Record the relevant before-state and rollback path.
  4. Classify the delivery shape:
    • Versioned artifact: read release workflows and only the matching section of publish targets.
    • Running app or service: read deploy workflows, then Environments or credentials when those boundaries change.
    • Both: publish one immutable payload, then deploy that payload instead of rebuilding it.
Use repo-local commands as authority. If the repository cannot reproducibly build, verify, package, observe, or roll back the claimed surface, report that prerequisite instead of hiding it in workflow YAML.
在修改文件或实时设置之前：
  1. 阅读仓库指南、清单、验证命令、发布或部署脚本、
    .github/
    目录、贡献者/安全文档，以及任何仓库专属的交付运行手册。
  2. 查看GitHub实时状态：默认分支、合并方式、生效的分支规则、Actions策略、环境、受保护标签、安全设置，以及所有受变更影响的人工或自动化默认分支写入者。
  3. 记录相关的变更前状态与回滚路径。
  4. 对交付类型进行分类：
    • 版本化工件：阅读发布工作流以及发布目标中匹配的章节。
    • 运行中的应用或服务：阅读部署工作流，当边界发生变化时，再阅读环境或凭据相关内容。
    • 两者兼具：发布一个不可变的负载，然后部署该负载，而非重新构建。
以仓库本地命令为权威依据。如果仓库无法可复现地构建、验证、打包、观测或回滚声明的交付内容，请先报告该前置条件，而非将其隐藏在工作流YAML中。

Shared Contract

通用约定

  • Pull requests execute untrusted code with read-only credentials.
  • Trusted release and deploy jobs load credentials only after verification and input or ref validation.
  • Workflow permissions default to read-only or 
    {}
    and widen per job.
  • High-trust remote Actions use reviewed immutable pins with an update path.
  • Environment secrets and policy match the release or deployment blast radius.
  • Release, publish, signing, promotion, and deploy critical sections are non-cancellable and reconcilable.
  • One verified payload crosses build, test, publish, and deploy boundaries.
  • Required checks use a stable final result when matrices, conditional lanes, or no-op paths make individual jobs unstable.
  • A green workflow is not completion until live settings and downstream state are read back.
Read Actions security before workflows execute project code, load secrets, publish, sign, or deploy.
When implementing rather than only auditing, read maintained implementations and start from the closest tested shape. Reuse its contract, not its literal versions, identities, or provider details.
  • 拉取请求使用只读凭据执行不受信任的代码。
  • 受信任的发布和部署作业仅在验证及输入或引用校验通过后才加载凭据。
  • 工作流权限默认设为只读或
    {}
    ，并按作业需求放宽权限。
  • 高信任度的远程Actions使用经过审核的不可变固定版本，并具备更新路径。
  • 环境密钥与策略匹配发布或部署的影响范围。
  • 发布、打包、签名、升级及部署的关键环节不可取消且可核对。
  • 一个经过验证的负载贯穿构建、测试、打包及部署环节。
  • 当矩阵、条件分支或无操作路径导致单个作业不稳定时，必填检查使用稳定的最终结果。
  • 只有当实时设置和下游状态被回读后，绿色工作流才算完成。
在工作流执行项目代码、加载密钥、打包、签名或部署之前，请阅读Actions安全相关内容。
当进行实现而非仅审核时，请阅读已维护的实现示例，并从最接近的已测试模板开始。复用其约定，而非字面版本、身份或服务商细节。

Repository Policy

仓库策略

Read repository settings for merge methods, rulesets, required checks, signed commits, tags, Actions policy, Environments, the cost-safe organization security baseline, CodeQL posture, and repository metadata.
Preserve existing approval, actor, signed-commit, tag, and status-check rules unless the requested change owns them. Running a check and enforcing it are separate operations. Before requiring pull requests or a check, inventory release bots, dependency bots, generated writebacks, and maintainers who still write the default branch.
阅读仓库设置了解合并方式、规则集、必填检查、签名提交、标签、Actions策略、环境、成本安全的组织安全基线、CodeQL状态及仓库元数据。
除非请求的变更明确要求，否则保留现有的审批、执行者、签名提交、标签及状态检查规则。运行检查与强制执行是两个独立的操作。在要求拉取请求或检查之前，请清点发布机器人、依赖机器人、生成的回写操作以及仍可写入默认分支的维护者。

Collaboration Files

协作文件

Read templates when adding or aligning pull-request templates, issue forms, 
SECURITY.md
, 
CONTRIBUTING.md
, or shared community defaults.
  • Prefer public owner-level defaults only for policy true across every repo.
  • Keep templates short and evidence-oriented; avoid checklist theater.
  • Public security guidance needs a working private reporting route. Private repos use an existing private maintainer channel.
  • Add Dependabot configuration only for ecosystems and manifests that exist. Keep scheduled updates low-noise and preserve compatibility constraints.
在添加或对齐拉取请求模板、问题表单、
SECURITY.md
、
CONTRIBUTING.md
或共享社区默认配置时，请阅读模板相关内容。
  • 仅当策略适用于所有仓库时，才优先使用公共所有者级别的默认配置。
  • 保持模板简洁且以证据为导向；避免形式化的检查清单。
  • 公共安全指南需要有效的私有报告渠道。私有仓库使用现有的私有维护者沟通渠道。
  • 仅针对已存在的生态系统和清单添加Dependabot配置。将定期更新设置为低干扰，并保留兼容性约束。

Release and Deploy Routes

发布与部署流程

Release work uses:
  • release workflows for trust, publication, signed writeback, immutable releases, recovery, and completion proof
  • publish targets for npm, Swift/CocoaPods, Go, Rust, GitHub Actions, Homebrew, and monorepos
  • semantic-release only when that tool is selected
  • release troubleshooting only after a concrete failure or inconsistent durable state
Deploy work uses:
  • deploy workflows for triggers, lane detection, verified payloads, concurrency, and monitoring handoff
  • Environments when target selection, protection, OIDC, or provider boundaries change
  • credentials when secret ownership or logging changes
  • deploy troubleshooting only after a concrete failure
发布工作使用：
  • 发布工作流用于信任验证、发布、签名回写、不可变发布、恢复及完成证明
  • 发布目标适用于npm、Swift/CocoaPods、Go、Rust、GitHub Actions、Homebrew及单体仓库
  • 仅当选择该工具时使用semantic-release
  • 仅在出现具体故障或持久状态不一致时使用发布故障排查
部署工作使用：
  • 部署工作流用于触发、分支检测、验证负载、并发控制及监控交接
  • 当目标选择、保护、OIDC或服务商边界发生变化时使用环境
  • 当密钥所有权或日志记录发生变化时使用凭据
  • 仅在出现具体故障时使用部署故障排查

Verify and Finish

验证与收尾

Run repository gates plus 
actionlint
and 
zizmor
when workflows changed. Perform the narrowest safe live proof of the delivery contract. Dry-runs and static inspection cannot prove immutable publication, signed writeback, registry or tap parity, deployment, monitoring, or rollback.
After authorized live changes, read back every setting, Environment, rule, release, registry, tag, deployment, or downstream pointer in scope. On partial failure, reconcile durable state before retrying; never create a new version or mutate an immutable release merely to make a workflow green.
当工作流发生变更时，运行仓库门禁检查以及
actionlint
和
zizmor
。执行交付约定的最窄范围安全实时验证。试运行和静态检查无法证明不可变发布、签名回写、注册表或源的一致性、部署、监控或回滚能力。
在完成授权的实时变更后，回读范围内的所有设置、环境、规则、发布、注册表、标签、部署或下游指针。如果出现部分失败，请先协调持久状态再重试；切勿仅为了让工作流显示为绿色而创建新版本或修改不可变发布。

Output

输出

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