为存储库配置代码扫描

用于配置 code scanning 的选项 #

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

• CodeQL：将 GitHub Actions 与任一默认设置配合使用（请参阅“为存储库配置代码扫描”）或与高级设置配合使用（请参阅“为存储库配置代码扫描”），或在第三方持续集成 (CI) 系统中运行 CodeQL 分析（请参阅“关于 CI 系统中的 CodeQL 代码扫描”）。

• Third‑party：使用 GitHub Actions （请参阅“为存储库配置代码扫描”）或第三方工具并将结果上传至 GitHub（请参阅“将 SARIF 文件上传到 GitHub”）。

  如果使用多个配置运行代码扫描，则有时多个配置会生成相同的警报。 如果警报来自多个配置，你可在警报页上查看每个配置的警报状态。 有关详细信息，请参阅“关于代码扫描警报”。

工具状态页 显示有关所有代码扫描工具的有用信息。 如果代码扫描未按预期运行，则 工具状态页 是调试问题的一个很好的起点。 有关详细信息，请参阅“关于代码扫描的工具状态页”。

自动配置 code scanning #

code scanning 的默认设置将自动使用存储库的最佳设置来配置 code scanning。 默认设置使用 GitHub Actions 运行 CodeQL 分析，无需将工作流文件提交到存储库。

如果存储库使用 GitHub Actions 并且仅包含以下 CodeQL 支持的语言，则其符合使用默认设置的条件：Go、JavaScript/TypeScript、Python 或 Ruby。 可以在存储库包含 CodeQL 不支持的语言（例如 R）时使用默认设置，但如果包含 CodeQL 支持的语言，而这些语言不属于之前列出的语言，则必须使用高级设置。 有关 CodeQL 支持的语言的详细信息，请参阅“关于使用 CodeQL 进行代码扫描”。有关批量启用的信息，请参阅“使用 CodeQL 大规模配置代码扫描”。

启用默认设置是为存储库配置 code scanning 的最快方法。 此外，默认设置不需要对 CodeQL 工作流文件进行任何维护。 在启用默认设置之前，可看到该设置将分析的语言和运行的查询套件，以及将触发新扫描的事件。

如果不需要运行额外的查询、更改扫描计划或扫描默认设置当前不支持的语言，请尝试默认设置。

1. 在 GitHub.com 上，导航到存储库的主页。 1. 在存储库名称下，单击 “设置”。 如果看不到“设置”选项卡，请选择 下拉菜单，然后单击“设置” 。

   

2. 在侧边栏的“安全性”部分中，单击“ 代码安全性和分析”。

3. 在“Code scanning”部分中，选择“设置”，然后单击“默认” 。

   

4. （可选）在“CodeQL 默认配置”模式对话框的“查询套件”部分，选择“默认值” 下拉菜单，然后单击要使用的 CodeQL 查询套件。

   

   如果选择扩展查询套件，那么除了默认查询套件中包含的查询外，code scanning配置还将运行严重程度和精确度较低的查询 。

   注意：如果将 code scanning 配置为使用扩展查询套件，则出现误报警报的概率可能更高 。

5. 查看存储库中默认设置的设置，然后单击“启用 CodeQL”。

   注意：

   • CodeQL 默认配置窗口显示默认设置的详细信息，包括要分析的语言、要运行的查询套件以及触发新扫描的事件。 如果要更改将触发新扫描的事件或自定义其他code scanning功能，则需要使用高级设置。 有关详细信息，请参阅“为存储库配置代码扫描”。
   • 如果要从高级设置切换到默认设置，则可看到一条警告，通知你默认设置将替代现有配置。 CodeQL 默认设置将禁用现有工作流文件，并阻止任何 CodeQL 分析 API 上传。
   • 如果要在配置后查看默认 CodeQL 设置，请选择 ，然后单击 “查看 CodeQL 配置”。

创建高级设置 #

需要自定义 code scanning 时，code scanning 的高级设置非常有用。 通过创建和编辑工作流文件，可以选择要运行的查询、更改扫描计划、扫描任何 CodeQL 支持的语言、使用矩阵生成等。

使用初学者工作流配置 code scanning #

GitHub 为 code scanning 等安全功能提供起始工作流。 您可以使用这些建议的工作流程来构建 code scanning 工作流程，而不是从头开始。 Code scanning 入门工作流仅在启用了 code scanning 时才可用于存储库。

使用操作运行 code scanning 将消耗分钟数。 有关详细信息，请参阅“关于 GitHub Actions 的计费”。

1. 在 GitHub.com 上，导航到存储库的主页。 1. 在你的存储库名称下，单击 “操作”。
2. 如果存储库已配置并运行至少一个工作流，请单击“新建工作流”以显示起始工作流。 如果当前没有为存储库配置工作流程，请转到下一步。
3. 在“选择工作流”或“GitHub Actions 入门”视图中，向下滚动到“安全性”类别，然后单击要配置的工作流下的“配置”。 可能需要单击“查看全部”以查找要配置的安全工作流。
4. 按照工作流中的任何说明，根据你的需要对其进行自定义。 有关工作流的更多常规帮助，请单击工作流页面右窗格中的“文档”。 有关详细信息，请参阅“使用入门工作流程”和“自定义代码扫描”。

手动配置 code scanning #

可以通过创建和编辑工作流文件来自定义 code scanning。 高级设置会生成一个基本工作流文件供你自定义。

使用操作运行 code scanning 将消耗分钟数。 有关详细信息，请参阅“关于 GitHub Actions 的计费”。

1. 在 GitHub.com 上，导航到存储库的主页。 1. 在存储库名称下，单击 “设置”。 如果看不到“设置”选项卡，请选择 下拉菜单，然后单击“设置” 。

   

2. 在侧边栏的“安全性”部分中，单击“ 代码安全性和分析”。

3. 向下滚动到“Code scanning”部分，选择“设置”，然后单击“高级” 。

   注意：如果要从默认设置切换到高级 code scanning 设置，请在“Code scanning”部分中，选择 ，然后单击 “切换到高级” 。 在出现的弹出窗口中，单击“禁用 CodeQL”。

   

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

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

   有关详细信息，请参阅“自定义代码扫描”。

5. 单击“提交更改...”

   

6. 在“提交消息”字段中，键入提交消息。

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

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

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

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

有关批量启用的信息，请参阅“使用 CodeQL 大规模配置代码扫描”。

查看来自 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 分析检查的名称采用形式："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 分析生成的日志。 有关详细信息，请参阅“查看代码扫描日志”。
• 调查初始配置 CodeQL code scanning 时发生的任何问题。 有关详细信息，请参阅“对 CodeQL 的高级设置进行故障排除”。
• 自定义 code scanning 如何扫描您的仓库中的代码。 有关详细信息，请参阅“自定义代码扫描”。