发布及使用 CodeQL 包

注意：CodeQL 包管理功能（包括 CodeQL 包）目前作为 beta 版本提供，可能会发生变化。在 beta 版本发布期间，CodeQL 包只能使用 GitHub 包，即 Container registry。若要使用此 beta 版本功能，请从以下位置安装最新版本的 CodeQL CLI 捆绑包： https://github.com/github/codeql-action/releases 。

在发布前配置 `qlpack.yml` 文件

可以在发布之前检查和修改 CodeQL 包的配置详细信息。在你喜欢的文本编辑器中打开 qlpack.yml 文件。

library: # set to true if the pack is a library. Set to false or omit for a query pack
name: <scope>/<pack>
version: <x.x.x>
description: <Description to publish with the package>
default-suite: # optional, one or more queries in the pack to run by default
    - query: <relative-path>/query-file>.ql
default-suite-file: default-queries.qls # optional, a pointer to a query-suite in this pack
license: # optional, the license under which the pack is published
dependencies: # map from CodeQL pack name to version range

name: 必须采用 / 格式，其中是将发布到的 GitHub 组织，是包的名称。
最多只能选择 default-suite 和 default-suite-file 中的一个。有两种不同的方法来定义要运行的默认查询套件，第一种是直接在 qlpack.yml 文件中指定查询，第二种是在包中指定查询套件。

正在运行 `codeql pack publish`

准备好将包发布到 GitHub Container registry 时，可在包目录的根目录中运行以下命令：

codeql pack publish

已发布的包将显示在 GitHub 组织的“包”部分中，该组织由 qlpack.yml 文件中的范围指定。

正在运行 `codeql pack download <scope>/<pack>`

若要运行其他人创建的包，必须先运行以下命令来下载它：

codeql pack download <scope>/<pack>@x.x.x

<scope>：将从中下载的 GitHub 组织的名称。
<pack>：要下载的包的名称。
@x.x.x：可选版本号。如果省略，将下载最新版本。

此命令接受多个包的参数。

如果编写脚本来指定要下载的查询包的特定版本号，请记住，在将 CodeQL 的版本更新为更新的版本时，可能还需要切换到更新的查询包版本。与固定到非常旧的版本的查询包一起使用时，较新版本的 CodeQL 可能会导致性能降低。有关详细信息，请参阅“关于 CodeQL 包兼容性”。

使用 CodeQL 包分析 CodeQL 数据库

若要使用 CodeQL 包分析 CodeQL 数据库，请运行以下命令：

codeql database analyze <database> <scope>/<pack>@x.x.x:<path>

<database>：要分析的 CodeQL 数据库。
<scope>：将包发布到的 GitHub 组织的名称。
<pack>：正在使用的包的名称。
@x.x.x：可选版本号。如果省略，将使用最新版本。
:<path>：查询、目录或查询套件的可选路径。如果省略，将使用包的默认查询套件。

analyze 命令将运行任何指定的 CodeQL 包的默认套件。可以指定多个用于分析 CodeQL 数据库的 CodeQL 包。例如：

codeql <database> analyze <scope>/<pack> <scope>/<other-pack>

注意：codeql pack download 命令将其下载的包存储在不用于本地修改的内部位置。如果在下载后修改包，可能会导致意外（且很难进行排除故障）的行为。有关自定义包的详细信息，请参阅“创建和使用 CodeQL 包”。

关于 CodeQL 包兼容性

发布查询包时，它包括其中所有查询的预编译表示形式。与在分析期间从头开始编译 QL 源相比，这些预编译查询的执行速度通常要快得多。但是，预编译的查询也依赖于 QL 计算器的某些内部信息，因此如果执行分析的 CodeQL 的版本与运行 codeql pack publish 的版本差异太大，则可能需要改为在分析期间从源编译查询。重新编译会自动进行，不会影响分析的结果，但会使分析速度明显变慢。

通常可以假设，如果包发布时包含 CodeQL 的一个版本，则 CodeQL 的更高版本可直接使用其中的预编译查询，只要发布日期之间的间隔不超过 6 个月即可。我们将做出合理的努力，使新版本的兼容性保持更长时间，但不做出任何承诺。

还可以假设由 CodeQL 的最新公开版本发布的包可供 code scanning 和 GitHub Actions 使用的 CodeQL 版本使用，即使该版本通常略微更旧也是如此。

上述情形的例外情况是，使用低于 2.12.0 的 CodeQL 版本发布的包与任何更低或更高版本不兼容。这些旧版本未按支持版本之间兼容性的格式编写预编译的查询。这些版本发布的包仍可由较新版本使用，但分析速度更慢，因为必须先重新编译查询。

作为已发布的查询包的用户，你可通过检查使用查询包的分析运行中的终端输出来检查 CodeQL 是否利用了其中预编译的查询。如果它包含如下所示的行，则已成功使用预编译的查询：

[42/108] Loaded /long/path/to/query/Filename.qlx.

但是，如果它们如下所示，则未能使用预编译的查询：

Compiling query plan for /long/path/to/query/Filename.ql.
[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql.

在这种情况下，分析结果仍然不错，但为了获得最佳性能，可能需要升级到 CodeQL CLI 和/或查询包的更新版本。

如果你在 GitHub.com 上的 Container registry 上发布查询包供其他人使用，建议使用最新版本的 CodeQL 来运行 codeql pack publish，并在使用的版本已过 6 个月之前发布包含 CodeQL 更新版本的包的新版本。这样，你可确保将 CodeQL 保持最新状态的包用户将受益于包中预编译的查询。

如果发布查询包的目的是在使用其捆绑的 CodeQL 二进制文件的 GitHub Enterprise Server 安装上使用查询包，请使用相同的 CodeQL 版本来运行 codeql pack publish。较新版本可能会生成预编译的查询，而 GitHub Enterprise Server 中的查询可能无法识别。 GitHub Enterprise Server 管理员可选择定期升级到更新版本的 CodeQL。如果是，请按照其指示操作。

对 GitHub Container registries 进行身份验证

可通过向相应的 GitHub Container registry 进行身份验证来发布包和下载专用包。

可通过两种方式向 GitHub.com 上的 Container registry 进行身份验证：

将 --github-auth-stdin 选项传递给 CodeQL CLI，然后通过标准输入提供 GitHub Apps 令牌或 personal access token。
将 GITHUB_TOKEN 环境变量设置为 GitHub Apps 令牌或 personal access token。

发布及使用 CodeQL 包

In this article

在发布前配置 qlpack.yml 文件

正在运行 codeql pack publish