注意：本文已于 2023 年 1 月从 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。