介绍
在本教程中，您将通过 Code Quality 的分析从第一个要合并的注释开始跟进单个拉取请求。 学习内容：
- 如何阅读有关拉取请求的 Code Quality 注释，并区分两种类型的调查结果。
- 如何使用查找的严重性标签来确定要修复的内容、要消除的内容以及顺序。
- 您对拉取请求所做的选择如何影响存储库的分数、积压工作和合并入口。
最后，您将解决示例拉取请求中发现的每个阻止问题，并将其与干净的 Code Quality 检查合并，并且您将了解做出每个选择的原因。
这是一次引导式演练，因此它更注重理解而非速度。 有关如何提交自动修复或忽略某项调查结果的基本步骤，请参阅配套操作指南：修复拉取请求中的代码质量问题。
在您开始之前
-
Code Quality 在您为其贡献内容的存储库上已启用。 请参阅“[AUTOTITLE](/code-security/how-tos/maintain-quality-code/enable-code-quality)”。 - 存储库使用支持 CodeQL 的语言，以便生成基于规则的查找和分数。 有关支持的语言列表，请参阅 GitHub 代码质量。
- 您有一个针对默认分支提出的拉取请求，其中至少有一个 Code Quality 调查结果需要会审。 如果尚未准备好拉取请求，可以按照以下示例操作。
在本教程中，我们将使用一个贯穿始终的示例：某个对部分代码进行重构的拉取请求，如果按原样合并到默认分支，会引入若干代码质量问题。 系统已自动对该拉取请求运行了 Code Quality 扫描，并已将若干发现以评论形式提出。
为什么拉取请求是修复发现的问题的最佳位置
您在拉取请求阶段未解决的每个问题都会成为存储库积压工作中的一个操作项，并且以后偿还技术债务通常比现在解决更昂贵。 现在，虽然拉取请求处于打开状态，但你对代码的上下文和意图仍然记忆犹新，这使得你可以更快地评估、应用或自信地消除每个调查结果及其自动修复。
在拉取请求阶段解决发现的问题意味着团队可以花更少的时间根据功能工作来归类修复工作，并避免只是为了消除积压工作而产生的额外拉取请求的开销。
步骤 1：查找有关拉取请求的 Code Quality 注释
当您创建拉取请求时，Code Quality 会运行 两种类型的分析，并将结果作为评论发布。 打开拉取请求的已更改的文件选项卡，查看每条评论是谁留下的 - 作者会告诉你这属于哪种类型的调查结果。
-
**基于规则的调查结果**由 **`github-code-quality[bot]`** 发布。 Code Quality 使用 CodeQL 根据一组规则扫描你的更改，并且每条评论都包含一项建议的自动修复。 -
由 AI 提供支持的发现 由 Copilot 发布。 如果您的组织拥有 Copilot 许可证，并且已为您的企业启用 AI 功能，Copilot 代码评审 会查找基于规则的分析可能遗漏的质量问题。 这些注释还包括建议的自动修复。
在我们的示例中，我们将查看来自 github-code-quality[bot]三个注释，因此它们是基于规则的发现。 在你自己的拉取请求里，你可能会看到这两种类型——在继续之前，先弄清楚哪种是哪种，因为严重程度标签（步骤 2）仅适用于基于规则的评论。
步骤 2：读取严重性标签以确定重要事项
每个基于规则的查找 github-code-quality[bot] 都带有严重性标签-“错误”、“ 警告”或 “注意”。 找到其中一条批注上的标签，并将其与此表进行核对。
| Severity | 定义 |
|---|---|
| Error | 表示可能导致 bug、故障或重大可维护性风险的高严重性问题。 |
| 警告 | 指示可能影响代码质量或可靠性的中等严重性问题，但并不立即至关重要。 |
| 备注 | 指示低严重性问题、轻微改进或建议。 这些发现对于代码的持续性健康状况和可维护性非常有用。 |
这个标签同时为你发挥两种作用：
- 它告诉你首先要修复什么。 严重性反映了规则在典型代码中的预期影响。 在我们的示例中，你应先处理 错误，然后处理 警告，并将 说明 视为可选的润色。
- 它可能决定是否可以完全合并。 仓库管理员或组织所有者可以将 Code Quality 配置为合并门禁。 例如，如果合并阈值为“警告及以上”，则必须修复或消除每个 警告和错误级别查找，然后才能合并（注意 发现不会阻止合并）。 同样，更严格的阈值可能需要在合并之前解决 所有 发现。
若要查看门禁是否生效，请滚动到拉取请求底部的 Checks 部分。 如果你的更改内容未达到所需阈值，你将看到一条合并被阻止的横幅提示：“合并被阻止：检测到代码质量问题。”
在我们的示例中，入口设置为“警告及以上”，因此会显示以下横幅：错误和警告会阻止合并，但注释不会。 这说明在合并此拉取请求之前必须清除哪些内容。
如果阻止合并操作横幅未指定严重性级别，则必须清除_所有_调查结果才能合并拉取请求。
步骤 3：解决每个发现问题
对于每个发现，请确定它是否适用于你的代码，如果适用，如何修复它。 这会让你采取以下三种操作中的一种。
| Assessment | 建议的操作 | 注释 |
|---|---|---|
| 发现是合法的，建议的修复看起来正确 | ||
| 应用自动修复建议 | 单击 提交建议 不会使用 AI credits，并且基于规则的自动修复不需要 Copilot 许可证。 | |
| 该问题确实存在，但你想一次性修复多个，或者建议的修复方案需要调整 | ||
委托给 Copilot- 在注释中提及 @copilot 将工作交给云代理。 Copilot 会与 👀 发生相互作用，启动新的智能体会话，并将必要的修复推送到拉取请求的分支 | 需要 Copilot 许可证，并消耗 AI credits。 | |
| 例如，此调查结果不适用：它是测试代码、有意模式或误报 | 单击忽略发现并提供原因 | 你将能够合并拉取请求，但调查结果将显示在存储库积压工作中，并且在将来的拉取请求中也会出现。 |
将这一做法应用于你自己的拉取请求，并按严重程度顺序进行处理。
在我们的示例中：
- 错误级和警告级的问题项确实是真正的缺陷，而且建议的自动修复看起来也很合理，因此我们采纳这些自动修复建议。 发现的问题得到解决并将不再计入阻止计数。
- 注释级别的调查结果会标记相邻测试帮助器中的次要模式。 这是有意的，所以我们以“在测试中使用”等原因消除它。
- 还有其他几个注释级别的调查结果。 我们不是逐条处理每个自动修复建议，而是添加评论：“
@copilot，修复所有剩余的注释级别问题”。 我们在存储库的智能体选项卡中跟踪 Copilot 的进度，并在准备就绪时查看推送到拉取请求的提交。
步骤 4：确认拉取请求已取消阻止（可选）
如果您确实存在阻止问题，在修复或忽略相关调查结果后，请返回到拉取请求底部的检查部分。
在我们的示例中，解决 “错误 ”和“ 警告 ”结果后，合并块横幅将消失。 你的拉取请求现在已可合并。
如果该横幅仍然存在，则表示严重性达到或高于阻止级别的调查结果仍处于打开状态。
步骤 5：解决来自 Copilot 的 AI 驱动的调查结果
如果你的组织拥有 Copilot 许可证，且你的企业已启用 AI 功能，你还会看到由 Copilot 发布的评论。 这些是在步骤 1 中引入的AI 生成的发现，这些发现来自Copilot 代码评审，而非github-code-quality[bot]。
如果基于规则的发现结果是将您的更改与一组固定的 CodeQL 规则进行匹配，Copilot 代码评审 则会推断您的代码意图。 它能发现那些无法归入某一具体规则的质量问题，因此，相较于替代基于规则的评注，它更适合作为对这类评注的有益补充。
这些发现不带有“错误”、“警告”或“注意”的严重性标签。 由于您在步骤 2 中看到的合并入口仅计数基于规则的调查结果的严重性，因此 AI 驱动的调查结果本身不会阻止您的拉取请求。 这并不意味着它们是可选项；结合上下文来解决这些问题，仍然是防止质量问题进入默认分支的最佳方式。
可以使用步骤 3 中使用的相同三个选项解决 AI 驱动的查找：
- 采用自动修复建议。 每条评论都包含一个建议的修复方案。 如果当前内容正确无误，请单击提交建议。 应用自动修复不会消耗 GitHub AI Credits。
- 委托给 Copilot- 在注释中提及
@copilot将工作交给云代理。 Copilot与 👀 交互，开启新的代理会话，并将必要的修复推送到拉取请求的分支。 此选项需要Copilot许可证，并且会消耗GitHub AI Credits。 - 解决注释。 如果它不适用于代码，请单击“ 解析”。
这与代码健康状况的其他部分有何关联
你刚才处理的拉取请求只是更广范围的一部分：
- 分数。 存储库的可靠性与可维护性分数是从默认分支上的发现计算得出的。 在合并之前解决调查结果是阻止这些分数偏离的方式。 请参阅“指标和评分参考”。
- 积压工作。 拉取请求中未修复的任何内容都会加入到默认分支上的调查结果的积压工作中。 逐步消化这些积压工作本身就是一门学问。 请参阅“提高存储库的代码质量分数”。
- 合 规。 当某一类发现结果确实绝不能进入默认分支时，“要求提供代码质量结果”规则集可帮助仓库管理员和组织所有者将这一决策设定为合并门禁。 请参阅“解决拉取请求中的阻塞”。
最健康的团队会将以下三者结合起来：在拉取请求阶段仔细考虑会审和修复，定期处理积压工作，并在合并边界强制执行阈值。
Troubleshooting
- 我看不到任何 Code Quality 评论。 扫描可能仍在运行，更改可能未触及受支持的语言，或者没有任何发现。 确认 Code Quality 已启用，并给出检查（称为“CodeQL - 代码质量”）完成的时间。 请参阅“启用 GitHub Code Quality”。
- 我只看到来自
github-code-quality[bot]的评论，从来没看到来自 Copilot 的评论。 AI 驱动的调查结果要求为您的企业启用 Copilot 许可证和 AI 功能。 如果没有它们，你将只看到基于规则的发现。 - 我看不到代码质量结果的自动修复。 自动修复生成会消耗 GitHub AI Credits。 你的组织可能已耗尽其每月预算 AI credits。
-
**阻止合并操作横幅无法清除。** 至少有一个严重性达到或高于阻止级别的调查结果仍处于打开状态。 如果在合并块横幅中看不到定义的严重性级别，这意味着存储库使用的是最严格的代码质量阈值，这要求在合并之前解决 *所有* 发现。 请参阅“[AUTOTITLE](/code-security/how-tos/maintain-quality-code/unblock-your-pr)”。
结束语
在本教程中，你已逐条处理拉取请求中的 Code Quality 评论，使用严重程度来确定修复优先级，并在合并拉取请求之前审慎地解决每一项发现的问题。 通过将每个发现的问题及其自动修复视为一个结合上下文的小决策，您可以防止默认分支出现代码质量债务。
后续步骤
- 对现有积压工作应用相同的思维： 提高存储库的代码质量分数。
- 了解结果如何转化为分数，以便你可以测量工作的影响： 指标和评分参考。