Skip to main content
我们经常发布文档更新，此页面的翻译可能仍在进行中。 有关最新信息，请访问英语文档。
All products
代码安全

创建并使用 CodeQL 包

本文内容

可以使用 CodeQL 包创建、共享、依赖和运行 CodeQL 查询和库。

GitHub CodeQL 在安装后按用户授权。 根据许可证限制，只能将 CodeQL 用于某些任务。 有关详细信息，请参阅“关于 CodeQL CLI”。

如果你有 GitHub Enterprise 帐户和GitHub Advanced Security 许可证，则可以使用 CodeQL 进行自动分析、持续集成和持续交付。 可以通过联系销售团队来创建企业帐户。 有关详细信息，请参阅“关于 GitHub 高级安全性”。

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

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

关于 CodeQL 包和 CodeQL CLI

使用 CodeQL 包和 CodeQL CLI 中的包管理命令，可以发布自定义查询并将其集成到代码库分析中。

有两种类型的 CodeQL 包：查询包和库包。

  • 查询包专为运行设计。 发布查询包时，此捆绑包中具有每个查询的所有可传递依赖项和预编译表示形式，还具有查询源。 这可确保一致且高效地执行包中的查询。
  • 库包旨在供查询包（或其他库包）使用，并且不包含查询本身。 库不单独。

可以使用 CodeQL CLI 中的 pack 命令创建 CodeQL 包、向包添加依赖项以及安装或更新依赖项。 还可以使用 pack 命令发布和下载 CodeQL 包。 有关详细信息，请参阅“发布和使用 CodeQL 包”。

有关已发布查询包与不同 CodeQL 版本之间的兼容性的详细信息，请参阅“关于 CodeQL 包兼容性”。

创建 CodeQL 包

可以通过从项目的签出根运行以下命令来创建 CodeQL 包：

codeql pack init <scope>/<pack>

必须指定以下内容：

  • <scope>：将发布到的 GitHub 组织或用户帐户的名称。

  • <pack>：正在创建的包的名称。

codeql pack init 命令为 CodeQL 包创建目录结构和配置文件。 默认情况下，此命令会创建查询包。 如果要创建库包，必须编辑 qlpack.yml 文件，通过包含 library:true 属性将文件显式声明为库包。

修改现有的旧版 QL 包以创建 CodeQL 包

如果已有 qlpack.yml 文件，可以手动编辑它，将其转换为 CodeQL 包。

  1. 编辑 name 属性，使其与格式 <scope>/<name> 匹配，其中 <scope> 是要发布到的 GitHub 组织或用户帐户的名称。

  2. 在 qlpack.yml 文件中，包括一个具有 semver 标识符的 version 属性，以及一个可选的 dependencies 块。

  3. 将 libraryPathDependencies 中的依赖项列表迁移到 dependencies 块。 为每个依赖项指定版本范围。 如果范围不重要，或者你不确定兼容性，则可以指定 "\*"，这指示任何版本都是可接受的，并在运行 codeql pack install 时默认为最新版本。

有关属性的详细信息，请参阅“关于 CodeQL 包”。

向 CodeQL 包添加和安装依赖项

可以使用命令 codeql pack add 添加对 CodeQL 包的依赖项。 必须指定范围、名称和（可选）兼容版本范围。

codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>

如果未指定版本范围，则将添加最新版本。 否则，将添加满足所请求范围的最新版本。

此命令使用请求的依赖项更新 qlpack.yml 文件，并将其下载到包缓存中。 请注意，此命令将重新格式化文件并删除所有注释。

还可以手动编辑 qlpack.yml 文件以包含依赖项，并使用以下命令安装依赖项：

codeql pack install

此命令将所有依赖项下载到本地磁盘上的共享缓存。

注意：

  • 运行 codeql pack add 和 codeql pack install 命令将生成或更新 codeql-pack.lock.yml 文件。 此文件应签入版本控制。 codeql-pack.lock.yml 文件包含包使用的确切版本号。 有关详细信息，请参阅“关于 codeql-pack.lock.yml 文件”。

  • 默认情况下，codeql pack install 将在 GitHub.com 上安装来自 Container registry 的依赖项。 可以通过创建 qlconfig.yml 文件从 GitHub Enterprise Server Container registry 安装依赖项。 有关详细信息，请参阅“发布和使用 CodeQL 包”。

自定义下载的 CodeQL 包

试验更改包的建议方法是克隆包含其源代码的存储库。

如果没有可用的源存储库，并且需要基于从 Container registry 下载的包进行修改，请注意，下载后不应修改或自定义这些包，并且其格式将来可能会更改，而不会另行通知。 如果需要修改内容，建议在下载包后执行以下步骤：

  • 更改 qlpack.yml 中的包名称，以避免与未修改的包的结果混淆。

  • 删除解压缩目录结构中任意位置的名为 *.qlx 的所有文件。 这些文件包含查询的预编译版本，在某些情况下，CodeQL 将优先使用它们，而不是已修改的 QL 源。