# 大规模推出 GitHub Code Quality

先在一小部分团队中试点，待质量阈值调整到位后再逐步扩展，这样就能有把握地将 Code Quality 推广到每个团队。

同时在所有地方开启 Code Quality 意味着每个团队都会在同一天开始在其拉取请求中看到 Code Quality 调查结果，这可能会令人惊讶，并具有破坏性。 在本教程中，你将了解如何分阶段推出它：先将发现引入小组，校准阈值，然后展开。 在推广到整个组织之前，你将先验证其价值。

## 先决条件

* 企业所有者已允许在你的企业中使用 Code Quality。 请参阅“[允许在您的企业中使用 GitHub Code Quality](/zh/code-security/how-tos/secure-at-scale/configure-enterprise-security/configure-specific-tools/allow-github-code-quality-in-enterprise?utm_campaign=code-quality-ga-july-2026\&utm_medium=docs\&utm_source=docs-roll-out-at-scale-enable-cq)”。
* 你是组织所有者，因此可以在组织级别启用 Code Quality 和配置规则集。

## 规划您的试点

**从小型试点组开始** ，而不是整个组织。 合适的试点对象可以是一个工程团队，或一组相关应用；它们应当足够活跃，能够产出有意义的发现，并且由能够就结果提供反馈的人负责。

若要以该组为目标，请使用组织的**存储库访问**设置来针对Code Quality。 对于试点，有两个很好的选择：

* **所选存储库：** 手动选取试点存储库的固定列表。 当试点组较小且稳定时，最好。
* **匹配筛选器：** 启用与定义的条件匹配的每个存储库，如自定义属性 `code-quality-enabled: true`。 当您希望试点随着团队标记更多存储库而自动增长时，这是最好的选择。

以自定义属性为目标，而不是逐个命名存储库，意味着以后只需在更多存储库上设置属性即可扩大试点范围。 如果要使用自定义属性：

1. 创建自定义属性。 请参阅“[管理组织中存储库的自定义属性](/zh/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization)”。
2. 在组织级别为与筛选条件匹配的仓库启用 Code Quality。 请参阅“[面向各类组织和企业的代码质量赋能](/zh/code-security/concepts/code-quality/enablement-at-scale#organization-level-repository-access)”。

## 在评估模式下启用质量规则集

**首先在评估模式下启用质量阈值。** 在此模式下，Code Quality会显示哪些拉取请求*会被*阻止，而不会实际阻止这些请求，因此试点团队可以在其开始强制执行之前了解其影响。

将阈值设置为试点存储库范围内的组织规则集，并将其保留在评估模式下，直到收集到足够的拉取请求活动来判断影响（通常是**一两周**）。 请参阅“[为拉取请求设置代码质量阈值](/zh/code-security/how-tos/maintain-quality-code/set-pr-thresholds)”。

## 调整阈值

**使用评估模式结果校准阈值。** 查看**规则集洞察**（规则集的历史记录），以准确了解哪些拉取请求本会被阻止及其原因。 如果太多拉取请求会被阻止，那么您的阈值可能比代码库所能适应的阈值更严格。 如果几乎没有任何内容会被拦截，你可能需要把这些规则设得更严格一些。 进行调整，直到门槛反映您实际想要执行的质量标准。

## 移动到强制模式

**当评估模式结果看起来正确时，请将规则集从“评估”切换到“活动”。** 这些阈值现在开始阻止不满足这些阈值的拉取请求。 试点团队会先经过这一强制门控环节，让你在进一步扩大推广范围之前做最后一次检查。

## 扩展到整个组织

**利用你从试点中获得的经验扩大推广范围。** 可以通过两种方式扩大它：

* 将 **存储库添加到所选存储库** 列表，或在与筛选器匹配的更多存储库上设置自定义属性。
* 确信阈值后，请将 **存储库访问** 设置切换到 **“所有存储库** ”，以在单个更改中在整个组织中应用 Code Quality 。

关于组织级启用的运作方式，有几点需要了解，以便你选择合适的方法：

* **存储库访问**选项**适用于现有存储库和将来的存储库**，因此以后创建的存储库会自动继承你的选择。 这适用于所有 **存储库**、 **匹配筛选器**和 **无存储库**。
* 启用**强制访问**，以保证实施一项存储库管理员无法替代的基线。 请将其关闭，或选择**让存储库决定**，以让团队选择在其自己的时间线上选择加入。

有关访问选项的完整列表以及强制实施方式，请参阅 [面向各类组织和企业的代码质量赋能](/zh/code-security/concepts/code-quality/enablement-at-scale#organization-level-repository-access)。

### 通过编程进行扩展

对于大多数推广场景，通过 UI 启用是最佳起点：这样你可以直接筛选并指定目标仓库，而这在脚本中更难复现。

如果你需要为发布流程实现自动化，可以通过 REST API 获取 Code Quality 发现结果，这有助于在逐步扩大范围时报告进展。 还可以通过 REST API 在存储库上启用 Code Quality ，以便跨组织编写启用脚本，而不是在 UI 中启用每个存储库。 请参阅“[代码质量的 REST API 端点](/zh/rest/code-quality/code-quality)”。

## 设置代码覆盖率

**调整阈值后，添加代码覆盖率。** 代码覆盖率独立于你在前面步骤中实施的质量阈值，因此你可以在团队认为合适的时候启用它；如果不想使用，也可以完全跳过。

启用 Code Quality 不会自动启用代码覆盖功能。 覆盖率需按仓库单独启用，并且只有在向仓库添加了上传覆盖率数据的工作流后，才会开始生成报告。 这意味着团队可以先采用 Code Quality ，以后再添加覆盖范围。

若要设置存储库的覆盖范围，请参阅 [为存储库设置代码覆盖率](/zh/code-security/how-tos/maintain-quality-code/set-up-code-coverage)。