仓库设置¶

GitHub 将这些设置存储在仓库之外，因此没有任何文件或 CI 检查可以强制执行它们。请以仓库管理员身份一次性应用这些设置，然后在更改工作流或作业名称后重新检查。下面的 gh api 命令假设你拥有一个已认证的 gh，并且对 debpalash/VoiceStudio 具有管理员访问权限。

推出 CLA 检查¶

在添加 .github/workflows/cla.yml 的拉取请求合并之后，按顺序执行以下操作：

1. 创建标签 cla（签署问题）和 cla-override（维护者审查）：gh label create cla 和 gh label create cla-override。
2. 打开公开的签署问题，为其添加 cla 标签，并将其置顶。
3. 在每个打开的拉取请求上评论 recheck，以便其获得 CLA 状态。在这些工作流存在之前打开的拉取请求还需要运行原生的 Commit identities 和 CLA gate 作业，以及 Commit identity policy：将当前的 main 合并到这些拉取请求中（合并协议反正也会要求这样做），或者关闭并重新打开它们。由评论触发的 CLA 运行会更新签名状态，但无法满足原生必需作业的要求。
4. 然后应用下面的 main 规则集。从未报告过的必需检查会以"Expected — waiting for status"阻止合并。
5. 在第一个签名创建分支后（或之前）应用 cla-signatures 规则集；该规则集可以先存在。

当你将其他人的拉取请求合并为一个时，请在描述中写入 Supersedes #N：这样检查也会要求这些拉取请求的作者签署。

规则集：main¶

要求必须有拉取请求、后端/前端测试作业、commit-identity 工作流及其特权策略状态、CLA 工作流作业及其签名状态，并阻止强制推送和删除。如果没有拉取请求规则，那么携带已通过检查的提交的直接推送会被接受。该规则不需要批准审查，因为 @debpalash 是唯一的维护者，而 GitHub 不允许作者批准自己的拉取请求。

每次 CLA 重新检查都会在查找贡献者和签名之前将头部提交标记为待处理（pending）。一旦 GitHub 接受该转换，后续的查找失败会使其保持待处理状态，而不是保留旧的批准。对已被取代的 PR 的查找失败不会被当作贡献者缺失。即使 GitHub 无法替换旧的 CLA 状态，状态写入失败也会导致必需的 CLA gate 作业失败。在 GitHub 恢复后，重新运行该失败的拉取请求工作流；问题评论触发的运行无法替代其原生检查。合并前必须通过这两项检查。

提交状态归属于某个 SHA，而不是某个特定的 PR。因此，两个资格检查器都会拒绝由多个打开的 PR 共享的头部提交，包括 CLA 维护者覆盖；一个 PR 不能用通过的检查结果覆盖另一个 PR 的义务。它会扫描所有打开的 PR，在列表错误或达到 1,000 个 PR 的安全上限时以失败关闭，并在正常成功之前再次检查。关闭重复 PR 会重新评估该 SHA 上剩余 PR 的 CLA。如果重复 PR 改为移动到另一个提交，请在幸存且仍保有旧头部提交的 PR 上评论 recheck。移除重复 PR 后，重新运行幸存者的受信任身份工作流：重复的头部提交会使其状态保持阻塞，直到新的评估成功，因此不会复用兄弟 PR 的描述结果。

这些检查是异步的，并不是合并时对 GitHub 元数据的原子锁。在编辑之后（包括关闭重复 PR），请等待最新的头部提交和元数据检查。评估期间检测到的元数据变化会使状态保持待处理，并导致原生作业失败；请重新运行该目标工作流。初始推出是刻意手动进行的：先让受信任的工作流落地，然后再将其上下文设为必需。能够发布提交状态的仓库写入者仍然处于管理信任边界之内。

context 值必须与拉取请求上显示的检查名称匹配：

• Tests (backend + frontend)：.github/workflows/ci.yml 中 test 作业的 name:。它是一个门禁，会等待 test-python 和 test-electron 作业，因此在更改其中任何一个时请保持此名称。
• Commit identities：.github/workflows/commit-identity.yml 中的原生作业。它仅通过 pull_request_target 运行属于基础分支的代码，并在 API、获取或策略执行错误时失败。PR 的提交以 git 对象的形式被获取；PR 的文件永远不会被检出，也没有由 PR 提供的引导回退机制。
• Commit identity policy：由 .github/scripts/identity_check.py 写入的特权提交状态。非特权 fork 工作流可以复制原生作业名称，但无法使用其只读令牌覆盖此状态。请同时要求原生作业和此状态。策略会读取当前 PR 元数据，并在发布前再次检查头部/基础分支/描述。过时的事件无法批准更新的头部提交，策略检出必须与当前基础分支 SHA 匹配；请将 PR 与 main 同步以获得新的运行。
• CLA gate：.github/workflows/cla.yml 中的原生作业，GitHub Actions 所要求的。即使 API 调用失败，拉取请求事件也会运行此作业，因此被拒绝的状态写入不会让合并门禁保持绿色。
• CLA：.github/scripts/cla_check.py 在拉取请求的头部提交上设置的提交状态。它检查签名资格；仅原生作业成功时，贡献者可能仍需要签署。请同时要求两者。

GitHub 将 pull_request_target 触发的原生作业评估为必需检查；issue_comment 作业不符合条件。请参阅 GitHub 的必需检查故障排除指南。

integration_id 15368 是 GitHub Actions，因此只有工作流运行才能满足原生检查。CLA 和 Commit identity policy 条目省略了它，因此状态计入受信任工作流使用的任何令牌。strict_required_status_checks_policy 要求分支在合并前与 main 保持最新。

gh api --method POST repos/debpalash/VoiceStudio/rulesets --input - <<'JSON'
{
  "name": "main",
  "target": "branch",
  "enforcement": "active",
  "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
  "bypass_actors": [
    { "actor_id": 5, "actor_type": "RepositoryRole", "bypass_mode": "pull_request" }
  ],
  "rules": [
    { "type": "deletion" },
    { "type": "non_fast_forward" },
    {
      "type": "pull_request",
      "parameters": {
        "required_approving_review_count": 0,
        "dismiss_stale_reviews_on_push": false,
        "require_code_owner_review": false,
        "require_last_push_approval": false,
        "required_review_thread_resolution": false
      }
    },
    {
      "type": "required_status_checks",
      "parameters": {
        "strict_required_status_checks_policy": true,
        "required_status_checks": [
          { "context": "Tests (backend + frontend)", "integration_id": 15368 },
          { "context": "Commit identities", "integration_id": 15368 },
          { "context": "Commit identity policy" },
          { "context": "CLA gate", "integration_id": 15368 },
          { "context": "CLA" }
        ]
      }
    }
  ]
}
JSON

该绕过机制允许仓库管理员合并其检查未通过的拉取请求，例如用来落地紧急修复，但绝不直接推送到 main。对于 CLA，请优先使用 cla-override 标签：它记录维护者已人工审查该拉取请求。如需更严格的设置，请移除该绕过条目。当 @debpalash 是唯一代码所有者时，请勿启用“要求代码所有者审查”，因为 GitHub 不允许作者批准自己的拉取请求。

UI：设置 → 规则 → 规则集 → 新建规则集 → 新建分支规则集。将目标设置为默认分支，启用 限制删除、合并前要求拉取请求（所需批准数：0，关闭所有其他选项）、阻止强制推送 和 要求状态检查通过，然后添加 Tests (backend + frontend)、Commit identities 和 CLA gate，来源为 GitHub Actions，外加 CLA 和 Commit identity policy 提交状态。

规则集：cla-signatures¶

.github/scripts/cla_check.py 在首次签名时创建该分支，并使用工作流的 GITHUB_TOKEN 将签名提交到该分支。该规则集仅阻止删除和强制推送。它不限制更新或要求检查，因此工作流可以持续提交。你可以在分支存在之前创建该规则集。

gh api --method POST repos/debpalash/VoiceStudio/rulesets --input - <<'JSON'
{
  "name": "cla-signatures",
  "target": "branch",
  "enforcement": "active",
  "conditions": { "ref_name": { "include": ["refs/heads/cla-signatures"], "exclude": [] } },
  "bypass_actors": [],
  "rules": [
    { "type": "deletion" },
    { "type": "non_fast_forward" }
  ]
}
JSON

使用 gh api repos/debpalash/VoiceStudio/rulesets 检查两个规则集。

机密扫描和推送保护¶

UI：设置 → 代码安全 → 机密保护。启用机密扫描和推送保护。

gh api --method PATCH repos/debpalash/VoiceStudio --input - <<'JSON'
{ "security_and_analysis": {
    "secret_scanning": { "status": "enabled" },
    "secret_scanning_push_protection": { "status": "enabled" } } }
JSON

提交在 backend/core/analytics.py 和 electron/src/shared/utils/analytics.ts 中的 PostHog 项目 token 按设计是一个可公开的只写 token（参见 tests/test_no_committed_analytics_token.py）。如果警报标记了它，请以“used in tests”或“false positive”为由关闭警报。不要移除该 token。

私有漏洞报告¶

.github/SECURITY.md 将 GitHub Security Advisories 列为首选渠道，而该链接仅在启用此设置时有效。

UI：设置 → 代码安全 → 私有漏洞报告 → 启用。

gh api --method PUT repos/debpalash/VoiceStudio/private-vulnerability-reporting

Dependabot 警报¶

UI：设置 → 代码安全 → Dependabot 警报 → 启用。此设置用于开启安全警报。GitHub Actions 的版本更新单独在 .github/dependabot.yml 中配置。

gh api --method PUT repos/debpalash/VoiceStudio/vulnerability-alerts

维护者提交邮箱¶

每位维护者应前往 GitHub → 设置 → 邮箱，启用 保留我的邮箱地址私密 和 阻止命令行推送暴露我的邮箱。然后将在该页面显示的 no-reply 地址设置为提交身份：

git config --global user.email "ID+USERNAME@users.noreply.github.com"

提交会保留其 GitHub 署名，而 scripts/cla_audit.py 无需 API 查找即可将 no-reply 地址映射到 GitHub 登录名。已经推送的提交会保留其旧地址。

贡献者审计对 HEAD 中的文本 blob 进行盘点，与暂存区改动无关。子模块 gitlink 被排除在外：其仓库需要单独的许可和贡献者审计。对某个已包含文件的 blame 失败会停止审计，而不是低估未签名贡献的数量。