使用多仓库变体分析在规模上运行 CodeQL 查询

使用多仓库变体分析（MRVA），您可以在 Visual Studio Code 中对最多 1,000 个 GitHub 仓库的列表运行 CodeQL 查询。

先决条件

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

• 在运行首个多仓库变体分析之前，必须先创建一个控制仓库。

• 控制仓库可以是空的，但必须至少有一次提交。

• 在 GitHub.com 上，如果您只计划分析公开仓库，则控制仓库的可见性可以设置为 “public”。此时变体分析是免费的。

• 如果需要分析任何私有或内部仓库，则控制仓库的可见性必须设置为 “private”。

对私有或内部仓库运行变体分析所使用的任何 Actions 分钟（超出免费额度的部分），都会计入仓库所有者的费用。有关免费分钟数和计费的更多信息，请参阅 GitHub Actions 计费。

为 MRVA 设置控制仓库

1. 在 “Variant Analysis Repositories” 视图中，点击 Set up controller repository（设置控制仓库）以显示控制仓库的输入字段。

   

2. 输入您想用作控制仓库的 GitHub 所有者和仓库名称，然后按下 Enter 键。

3. 如果系统提示您进行 GitHub 身份验证，请按照指示登录您的账户。完成后，GitHub Authentication 可能会弹出请求在 Visual Studio Code 中打开的权限，点击 Open（打开）。

控制仓库的名称会保存在 CodeQL 扩展的设置中。有关如何编辑控制仓库的说明，请参阅 自定义设置。

使用 MRVA 在规模上运行查询

1. 默认情况下，“Variant Analysis Repositories” 视图会显示针对您正在分析的语言的 GitHub.com 上前 10、前 100 和前 1000 个公开仓库的默认列表。如果您的控制仓库托管在 SUBDOMAIN.ghe.com，则这些列表不可用。

2. 您也可以自行添加新的仓库、组织或列表。

   1. 在 “Variant Analysis Repositories” 视图中，点击 + 添加新数据库。

   2. 在下拉菜单中，选择 From a GitHub repository（来自 GitHub 仓库）或 All repositories of GitHub org or owner（GitHub 组织或所有者的所有仓库）。

   3. 在字段中输入您想使用的仓库或组织的标识符。

3. 选择要对其运行查询的 GitHub 仓库或仓库集合。

   

4. 打开要运行的查询文件，在查询文件中右键单击并选择 CodeQL: Run Variant Analysis（运行变体分析）以启动变体分析。

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

1. 在 “Variant Analysis Repositories” 视图中，点击 + 添加新数据库。

2. 在下拉菜单中，选择 From a GitHub repository（来自 GitHub 仓库）或 All repositories of GitHub org or owner（GitHub 组织或所有者的所有仓库）。

3. 在字段中输入您想使用的仓库或组织的标识符。

错误和警告

在运行 MRVA 时，有两个关键位置会显示错误和警告：

• Visual Studio Code 错误：在创建 CodeQL 包或将分析发送到 GitHub 过程中出现的任何问题，都会在应用程序右下角以 VS Code 错误的形式报告，并可在 “Problems” 视图中查看详细信息。

• “Variant Analysis Results”：变体分析运行期间出现的任何问题会在此视图中报告。

浏览您的结果

一旦在 GitHub 上运行变体分析的工作流启动，“Variant Analysis Results” 视图就会打开，并在结果准备好时显示。您可以使用此视图监控进度、查看错误，且可以在控制仓库中访问工作流日志。

当您的变体分析运行被调度时，“Results” 视图会自动打开。起始时，它会列出所有已调度进行分析的仓库。随着每个仓库的分析完成，视图会更新并显示结果数量的概要。要查看某个仓库的详细结果（包括结果路径），请点击该仓库名称。

对于每个仓库，您可以看到：

• 查询发现的结果数量

• 仓库的可见性

• 分析是仍在进行中还是已完成

• 仓库在 GitHub 上的 star 数量

查看仓库的结果

1. 点击仓库名称即可展开每个结果的概要。

2. 使用指向 GitHub 上源文件的链接来探索每个结果的详细信息。对于数据流查询，还会出现 “Show paths”（显示路径）链接。

   

导出您的结果

您可以导出结果以便进一步分析或与协作者讨论。在 “Results” 视图中，点击 Export results（导出结果），将结果导出到 GitHub 的私密 gist，或导出为工作区中的 Markdown 文件。

创建自定义仓库列表

1. 在 “Variant Analysis Repositories” 视图中，点击 “Add list”（添加列表）图标。

   

2. 为新列表输入名称，然后按 Enter 键。

3. 在视图中选中您的列表，然后点击 + 将仓库添加到该列表。

管理自定义仓库列表

您可以通过右键单击列表名称或列表中的仓库名称，并从上下文菜单中选择相应选项来管理和编辑自定义列表。

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

例如，如果您想继续分析在查询中产生结果的一组仓库，可在 “Variant Analysis Results” 视图中点击 Copy repository list（复制仓库列表），将仅包含有结果的仓库列表以 JSON 形式复制到剪贴板。

下面的示例片段中，my-organization/my-repository 对查询产生了结果。

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

随后，您可以将该 new-repo-list 插入到 databases.json 中，以便在 “Variant Analysis Repositories” 视图中轻松访问。

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

您可以直接在 CodeQL 扩展中使用代码搜索，将符合条件的 GitHub 仓库子集添加到自定义列表。

例如，要将 GitHub 上 rails 组织的所有仓库添加进去，可搜索 org:rails。

每次搜索最多只能向自定义列表中添加 1,000 个仓库。

1. 在 “Variant Analysis Repositories” 视图中，选择要向其添加仓库的列表。您可以创建新列表，也可以选择已有仓库的现有列表。

2. 右键单击所选列表，然后点击 Add repositories with GitHub code search（使用 GitHub 代码搜索添加仓库）。

3. 在应用程序顶部弹出的窗口中，在搜索栏下方的下拉框中选择搜索语言。

4. 在搜索栏中输入您想使用的查询并按 Enter 键。

您可以在应用右下角的 Searching for repositories...（正在搜索仓库...）框中查看搜索进度。若点击 Cancel，则不会向列表添加任何仓库。搜索完成后，结果仓库会出现在 “Variant Analysis Repositories” 视图中您自定义列表下的下拉框中。

部分结果仓库可能没有 CodeQL 数据库，或可能不允许 CodeQL for VS Code 扩展访问。运行列表分析时，“Variant Analysis Results” 视图会显示哪些仓库已被分析、哪些被拒绝访问以及哪些缺少 CodeQL 数据库。

在自托管运行器上使用多仓库变体分析运行 CodeQL 查询

要在自托管运行器上使用多仓库变体分析运行 CodeQL 查询，首先需要确保已向您的控制仓库添加自托管运行器，或确保控制仓库能够访问组织级或企业级的自托管运行器。

接下来，需要在控制仓库中添加一个新的 Actions 仓库变量，名称为 MRVA_RUNNER_OS，其值为包含您希望使用的自托管运行器标签的 JSON 列表。例如：

["self-hosted", "macOS", "ARM64"]

更多信息请参阅 添加自托管运行器 与 使用组管理自托管运行器的访问权限。

当您在自托管运行器上使用多仓库变体分析运行查询时，分析全部在该自托管运行器上执行。您无需创建新的工作流，但必须指定 CodeQL for Visual Studio Code 扩展应使用哪个仓库作为控制仓库。随着每个仓库的分析完成，结果会发送回 VS Code 供您查看。