大规模运行 CodeQL 查询及多仓库变体分析 - GitHub 文档

关于使用多代码库变体分析大规模运行 CodeQL 查询

使用多代码库变体分析 (MRVA)，您可以使用 Visual Studio Code 在 GitHub 上最多 1,000 个代码库的列表上运行 CodeQL 查询。

当您针对代码库列表运行 MRVA 时，您的查询将在每个具有可供分析的 CodeQL 数据库的代码库上运行。GitHub 会创建和存储数千个公共代码库（包括每个使用 CodeQL 运行代码扫描的代码库）的默认分支的最新 CodeQL 数据库。

您需要在将代码库添加到分析列表之前，在 GitHub 上启用使用 CodeQL 的代码扫描，可以使用默认设置或高级设置。有关启用使用 CodeQL 的代码扫描的信息，请参阅“配置代码扫描的默认设置”。

MRVA 如何在 GitHub.com 上针对 CodeQL 数据库运行查询

运行 MRVA 时，分析完全使用 GitHub Actions 运行。您不需要创建任何工作流，但必须指定 CodeQL for Visual Studio Code 扩展应使用哪个代码库作为控制器代码库。每个代码库的分析完成后，结果都会发送到 VS Code 供您查看。

CodeQL 扩展使用您的库和任何库依赖项构建 CodeQL 包。CodeQL 包和您选择的代码库列表将发布到 GitHub 上的 API 端点，这会在您的控制器代码库中触发 GitHub Actions 动态工作流。该工作流会启动多个并行作业以对列表中的代码库执行 CodeQL 查询，从而优化查询执行。分析每个代码库后，结果将进行处理并在 VS Code 中显示。

先决条件

您必须在运行第一个多代码库变体分析之前定义控制器代码库。
控制器代码库可以为空，但必须至少有一个提交。
在 GitHub.com 上，如果您计划只分析公共代码库，则控制器代码库可见性可以为“公共”。变体分析将免费。
如果您需要在 GitHub.com 上分析任何私有或内部代码库，则控制器代码库可见性必须为“私有”。

超出免费限额的用于在私有或内部代码库上运行变体分析的任何 Actions 分钟将计费给代码库所有者。有关免费分钟和计费的更多信息，请参阅“关于 GitHub Actions 的计费”。

为 MRVA 设置控制器代码库

在“变体分析代码库”视图中，单击**设置控制器代码库**以显示控制器代码库的字段。
键入您要在 GitHub 上用作控制器代码库的代码库的所有者和名称，然后按**Enter**键。
如果系统提示您使用 GitHub 进行身份验证，请按照说明操作并登录到您的帐户。完成后，GitHub 身份验证的提示可能会请求允许在 Visual Studio Code 中打开，请单击**打开**。

控制器代码库的名称将保存在 CodeQL 扩展的设置中。有关如何编辑控制器代码库的信息，请参阅“自定义设置”。

使用 MRVA 大规模运行查询

默认情况下，“变体分析代码库”视图显示 GitHub.com 上针对您正在分析的语言的前 10 个、前 100 个和前 1000 个公共代码库的默认列表。如果您的控制器代码库托管在 SUBDOMAIN.ghe.com 上，则这些列表不可用。
或者，您可以添加新的代码库、组织或列表。
1. 在“变体分析存储库”视图中，单击+添加新的数据库。
2. 从下拉菜单中选择从 GitHub 存储库或GitHub 组织或所有者的所有存储库。
3. 在字段中输入要使用的存储库或组织的标识符。
选择要针对其运行查询的 GitHub 存储库。
打开要运行的查询，右键单击查询文件，然后选择CodeQL：运行变体分析以启动变体分析。

注意

要取消变体分析运行，请在“变体分析结果”视图中单击停止查询。

选择单个 GitHub 存储库或组织进行分析

在“变体分析存储库”视图中，单击+添加新的数据库。
从下拉菜单中选择从 GitHub 存储库或GitHub 组织或所有者的所有存储库。
在字段中输入要使用的存储库或组织的标识符。

错误和警告

运行 MRVA 时，有两个主要位置会显示错误和警告

Visual Studio Code 错误：创建 CodeQL 包并将分析发送到 GitHub 的任何问题都将作为 Visual Studio Code 错误报告在应用程序的右下角。信息也可在“问题”视图中找到。
“变体分析结果”：此视图中将报告变体分析运行中的任何问题。

浏览结果

在 GitHub 上运行变体分析的工作流运行后，将打开“变体分析结果”视图以显示已准备好的结果。您可以使用此视图监控进度，查看任何错误以及访问控制器存储库中的工作流日志。

Screenshot of "Variant Analysis Results" showing a run for "FileAccessToHttp.ql". Blue circles show the number of results found or "-" still running.

计划变体分析运行后，“结果”视图将自动打开。最初，视图将显示每个已计划进行分析的存储库的列表。对每个存储库进行分析后，视图将更新为显示结果数量的摘要。要查看存储库的详细结果（包括结果路径），请单击存储库名称。

对于每个存储库，您可以看到

查询找到的结果数
存储库的可见性
分析是否仍在运行或已完成
存储库在 GitHub 上获得的星标数

查看存储库的结果

单击存储库名称以显示每个结果的摘要。
使用指向 GitHub 上源文件的链接浏览每个结果的可用信息。对于数据流查询，将有一个额外的“显示路径”链接。

导出结果

您可以导出结果以进行进一步分析或与协作者讨论。在“结果”视图中，单击导出结果将结果导出到 GitHub 上的秘密 gist 或工作区中的 Markdown 文件。

创建自定义存储库列表

注意

CodeQL 分析始终需要 CodeQL 数据库才能运行查询。当您针对存储库列表运行变体分析时，您的查询将仅针对当前具有可下载 CodeQL 数据库的存储库执行。使存储库可用于变体分析的最佳方法是启用使用 CodeQL 的代码扫描。有关启用使用 CodeQL 的代码扫描的信息，请参阅“配置代码扫描的默认设置”。

在“变体分析存储库”视图中，单击“添加列表”图标。
键入新列表的名称，然后按Enter。
在视图中选择您的列表，然后单击+将存储库添加到您的列表。

管理您的自定义存储库列表

您可以通过右键单击列表名称或列表中的存储库名称，然后从上下文菜单中选择一个选项来管理和编辑自定义列表。

自定义列表存储在工作区中的databases.json文件中。如果您想直接在 Visual Studio Code 中编辑此文件，可以通过单击视图标题中的{ }来打开它。

例如，如果您想继续分析对您的查询有结果的一组存储库，请单击“变体分析结果”视图中的复制存储库列表，将仅包含有结果的存储库的列表作为 JSON 复制到剪贴板。

在以下示例代码段中，my-organization/my-repository对查询有结果

{
    "name": "new-repo-list",
    "repositories": [
        "my-organization/my-repository"
    ]
}

然后，您可以将存储库的new-repo-list插入databases.json，以便在“变体分析存储库”视图中轻松访问。

使用 GitHub 代码搜索将存储库添加到自定义列表

注意

此功能使用通过 GitHub 代码搜索 API 的旧版代码搜索。有关要使用的语法的更多信息，请参阅“搜索代码（旧版）”。

您可以直接在 CodeQL 扩展中使用代码搜索将 GitHub 的存储库子集添加到自定义列表。

例如，要添加 GitHub 上rails组织中的所有存储库，请搜索org:rails。

每次搜索最多可以向自定义列表添加 1,000 个存储库。

在“变体分析存储库”视图中，选择要向其添加存储库的列表。您可以创建一个新列表或选择一个已包含存储库的现有列表。
右键单击您选择的列表，然后单击使用 GitHub 代码搜索添加存储库。
在应用程序顶部搜索栏下出现的弹出窗口中，从下拉列表中的选项中选择搜索语言。
在搜索栏中，键入要使用的搜索查询，然后按Enter。

您可以在应用程序右下角的文本框中查看搜索进度，其中显示文本正在搜索存储库...。如果您单击取消，则不会将任何存储库添加到您的列表。完成后，您将看到结果存储库出现在“变体分析存储库”视图中自定义列表下的下拉列表中。

某些结果存储库将没有 CodeQL 数据库，有些可能不允许 Visual Studio Code 的 CodeQL 扩展访问。当您对列表运行分析时，“变体分析结果”视图将显示哪些存储库已分析，哪些被拒绝访问以及哪些没有 CodeQL 数据库。

使用多代码库变体分析大规模运行 CodeQL 查询

本文内容