为存储库配置代码扫描

用于配置 code scanning 的选项

在仓库级别决定如何生成 code scanning 警报，以及使用哪些工具。 GitHub AE 对 CodeQL 分析提供完全集成的支持，还支持使用第三方工具进行分析。 有关详细信息，请参阅下面的要点和“关于 code scanning”。

• CodeQL：使用 GitHub Actions（请参阅下文）或在第三方持续集成 (CI) 系统中运行 CodeQL 分析（请参阅“关于 CI 系统中的 CodeQL code scanning”）。

• 第三方：使用 GitHub Actions 或第三方工具和将结果上传到 GitHub AE（请参阅“将 SARIF 文件上传到 GitHub”）。

先决条件

在为存储库配置 code scanning 之前，必须确保存储库至少有一个自托管 GitHub Actions 运行器可用。

企业所有者、组织和存储库管理员可以添加自托管运行器。 有关自托管运行器的信息，请参阅“关于自托管运行器”和“添加自托管运行器”。

手动配置 code scanning

1. 在 your enterprise 上，导航到存储库的主页。 1. 在存储库名称下，单击“ 安全性”。

2. 在“Code scanning 警报”右侧，单击“设置 code scanning”。如果 code scanning 缺失，则需要让组织所有者或存储库管理员启用 GitHub Advanced Security。有关详细信息，请参阅“管理组织的安全性和分析设置”或“管理存储库的安全性和分析设置”。

3. 在“开始使用 code scanning”下，单击 CodeQL analysis workflow 或第三方工作流上的“设置此工作流”。 只有在工作流与在存储库中检测到的编程语言相关时，才会显示工作流。 CodeQL analysis workflow 始终显示，但仅在 CodeQL 分析支持存储库中存在的语言时才启用“设置此工作流”按钮。

4. 要自定义 code scanning 扫描代码的方式，请编辑工作流程。

   通常，可以提交 CodeQL analysis workflow 而无需对其进行任何更改。 但是，许多第三方工作流需要额外的配置，因此请在提交之前读取工作流中的注释。

   有关详细信息，请参阅“自定义 code scanning”。

5. 使用“开始提交”下拉列表，然后键入提交消息。

6. 选择是直接提交到默认分支，还是创建新分支并启动拉取请求。

7. 单击“提交新文件”或“建议新文件”。

在建议的 CodeQL analysis workflow 中，code scanning 配置为在每次将更改推送到默认分支或任何受保护分支或者对默认分支提出拉取请求时分析代码。 因此，code scanning 将立即开始。

用于代码扫描的 on:pull_request 和 on:push 触发器各自用于不同的目的。 有关详细信息，请参阅“自定义 code scanning”。

批量配置 code scanning

可以使用脚本在多个存储库中一次配置 code scanning。 如果要使用脚本发起将 GitHub Actions 工作流添加到多个存储库的拉取请求，请参阅 jhutchings1/Create-ActionsPRs 存储库，了解使用 PowerShell 的示例，或者对于没有 PowerShell 但希望改用 NodeJS 的团队，请参阅 nickliffen/ghas-enablement。

查看来自 code scanning 的日志记录输出

为存储库配置 code scanning 后，可以监视操作运行时的输出。

1. 在你的存储库名称下，单击 “操作”。

   You can view the run status of code scanning and get notifications for completed runs. For more information, see "Managing a workflow run" and "Configuring notifications." 条目的文本是提交消息的标题。

   

2. 单击 code scanning 工作流程的项目。

3. 单击左侧的作业名称。 例如，“分析(语言)”。

   

4. 查看此工作流运行时操作的日志记录输出。

5. 在所有作业完成后，您可以查看已识别的任何 code scanning 警报的详细信息。 有关详细信息，请参阅“管理存储库的 code scanning 警报”。

了解拉取请求检查

设置在拉取请求上运行的每个 code scanning 工作流程始终有至少两个条目列在拉取请求的检查部分中。 工作流程中每个分析作业有一个条目，最后还有一个对应于分析结果的条目。

code scanning 分析检查的名称采用形式："TOOL NAME / JOB NAME (TRIGGER)"。 例如，对于 CodeQL，C++ 代码的分析有条目 "CodeQL / Analyze (cpp) (pull_request)"。 可单击 code scanning 分析条目上的“详细信息”来查看日志记录数据。 这允许您在分析作业失败时调试问题。 例如，对于编译的语言的 code scanning 分析，如果操作无法生成代码，则可能会发生这种情况。

当 code scanning 作业完成后， GitHub 检查拉取请求是否添加了任何警报，并将“Code scanning 结果/工具名称”条目添加到检查列表中。 在执行至少一次 code scanning 后，可单击“详细信息”查看分析结果。

如果使用拉取请求将 code scanning 添加到存储库，则单击“Code scanning 结果/工具名称”检查中的“详细信息”时，最初会看到“找不到分析”消息。

该表列出了一个或多个类别。 每个类别都与针对相同工具和提交的特定分析相关，这些分析在不同的语言或代码的不同部分上执行。 对于每个类别，该表显示了 code scanning 尝试比较以确定在拉取请求中引入或修复了哪些警报的两个分析。

例如，在上面的屏幕截图中，code scanning 找到了针对拉取请求的合并提交的分析，但没有针对主分支头部的分析。

“未找到分析”消息出现的原因

在 code scanning 分析拉取请求中的代码后，它需要将主题分支（用于创建拉取请求的分支）的分析与基本分支（要合并拉取请求的分支）的分析进行比较。 这允许 code scanning 计算哪些警报是拉取请求新近引入的，哪些是基础分支中已经存在的，以及是否有任何现有的警报通过拉取请求中的更改来修复。 最初，如果使用拉取请求将 code scanning 添加到仓库，则尚未分析基础分支，因此无法计算这些详细信息。 在这种情况下，单击拉取请求的结果检查时，你将看到“找不到分析”消息。

在其他情况下，可能没有分析对拉取请求的基础分支的最新提交。 其中包括：

• 已针对默认分支以外的分支提出拉取请求，并且尚未分析此分支。

  若要检查是否扫描了分支，请转到 Code scanning 页面，单击“分支”下拉菜单并选择相关分支。

  

  在这种情况下，解决方案是将基本分支的名称添加到该分支上 code scanning 工作流的 on:push 和 on:pull_request 规格中，然后进行更改以更新要扫描的开放拉取请求。

• 目前正在分析拉取请求的基础分支上的最新提交，分析尚未提供。

  等待几分钟，然后将更改推送到拉取请求以重新触发 code scanning。

• 在分析基础分支上的最新提交时发生了错误，且该提交的分析不可用。

  将一个微小的更改合并到基础分支以触发此最新提交的 code scanning，然后将更改推送到拉取请求以重新触发 code scanning。

后续步骤

配置 code scanning 并允许其操作完成后，你可以：

• 查看为此仓库生成的所有 code scanning 警报。 有关详细信息，请参阅“管理存储库的 code scanning 警报”。
• 查看在配置 code scanning 后提交的拉取请求生成的任何警报。 有关详细信息，请参阅“会审拉取请求中的 code scanning 警报”。
• 为已完成的运行配置通知。 有关详细信息，请参阅“配置通知”。
• 查看由 code scanning 分析生成的日志。 有关详细信息，请参阅“查看 code scanning 日志”。
• 调查初始配置 CodeQL code scanning 时发生的任何问题。 有关详细信息，请参阅“排查 CodeQL 工作流的问题”。
• 自定义 code scanning 如何扫描您的仓库中的代码。 有关详细信息，请参阅“自定义 code scanning”。