发布及使用 CodeQL 包

注意：本文已于 2023 年 1 月从 CodeQL 文档网站迁移。

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

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

注意：本文介绍了 GitHub Enterprise Server 3.7 的初始发行版中包含的 CodeQL CLI 2.10.5 捆绑包中可用的功能。

如果站点管理员已将 CodeQL CLI 版本更新为较新版本，请参阅本文的 GitHub Enterprise Cloud 版本，了解有关最新功能的信息。

可以在发布之前检查和修改 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 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>

在 GitHub Enterprise Server 上使用 CodeQL 包

默认情况下，CodeQL CLI 预期从 GitHub.com 上的 Container registry 下载 CodeQL 包，并将这些包发布到此位置。不过，也可通过创建 qlconfig.yml 文件来告知 CLI 每个包使用哪个 Container registry，使用 GitHub Enterprise Server 上的 Container registry 中的 CodeQL 包。

使用首选文本编辑器创建 ~/.codeql/qlconfig.yml 文件，并添加条目来指定要用于一个或多个包名称模式的注册表。例如，以下 qlconfig.yml 文件将所有包与位于 GHE_HOSTNAME 的 GitHub Enterprise Server 的 Container registry 进行关联，但与 codeql/\* 匹配的包除外，它们与 GitHub.com 上的 Container registry 关联：

registries:
- packages:
  - 'codeql/*'
  - 'other-org/*'
  url: https://ghcr.io/v2/
- packages: '*'
  url: https://containers.GHE_HOSTNAME/v2/

CodeQL CLI 将通过查找 registries 列表中具有与该包名称匹配的 packages 属性的第一项来确定要用于给定包名称的注册表。这意味着，通常需要先定义最具体的包名称模式。 packages 属性可以是单个包名称、glob 模式，也可以是包名称和 glob 模式的 YAML 列表。

registries 列表也可以放在 codeql-workspace.yml 文件中。这样，便可定义要在特定工作区中使用的注册表，以便可在工作区的其他 CodeQL 用户之间共享该注册表。 codeql-workspace.yml 中的 registries 列表将与全局 qlconfig.yml 中的列表合并，并优先于后者。有关 codeql-workspace.yml 的详细信息，请参阅关于 CodeQL 工作区。

现在可以使用 codeql pack publish、codeql pack download 和 codeql database analyze 来管理 GitHub Enterprise Server 上的包。

对 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。

同样，可以向 GitHub Enterprise Server Container registry 进行身份验证，或者通过两种方式同时向多个注册表进行身份验证（例如，从多个注册表下载或运行专用包）：

将 --registries-auth-stdin 选项传递给 CodeQL CLI，然后通过标准输入提供注册表身份验证字符串。
将 CODEQL_REGISTRIES_AUTH 环境变量设置为注册表身份验证字符串。

注册表身份验证字符串是一个逗号分隔的 <registry-url>=<token> 对列表，其中 registry-url 是 Container registry URL（例如 https://containers.GHE_HOSTNAME/v2/），token 是 GitHub Apps 令牌或该 GitHub Container registry 的 personal access token。这可确保每个令牌仅传递到指定的 Container registry。例如，以下注册表身份验证字符串指定 CodeQL CLI 应使用 <token1> 令牌向 GitHub.com 上的 Container registry 进行身份验证，使用 GHE_HOSTNAME 令牌向位于 <token2> 的 GHES 实例的 Container registry 进行身份验证：

https://ghcr.io/v2/=<token1>,https://containers.GHE_HOSTNAME/v2/=<token2>

发布及使用 CodeQL 包

本文内容

在发布前配置 qlpack.yml 文件

正在运行 codeql pack publish