The Wayback Machine - https://web.archive.org/web/20230207040034/https://docs.github.com/zh/code-security/codeql-cli/using-the-codeql-cli/creating-and-working-with-codeql-packs
Skip to main content
我们经常发布文档更新，此页面的翻译可能仍在进行中。 有关最新信息，请访问英语文档。

Creating and working with CodeQL packs

本文内容

You can use CodeQL packs to create, share, depend on, and run CodeQL queries and libraries.

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

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

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

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

About CodeQL packs and the CodeQL CLI

With CodeQL packs and the package management commands in the CodeQL CLI, you can publish your custom queries and integrate them into your codebase analysis.

There are two types of CodeQL packs: query packs and library packs.

  • Query packs are designed to be run. When a query pack is published, the bundle includes all the transitive dependencies and pre-compiled representations of each query, in addition to the query sources. This ensures consistent and efficient execution of the queries in the pack.
  • Library packs are designed to be used by query packs (or other library packs) and do not contain queries themselves. The libraries are not compiled separately.

You can use the pack command in the CodeQL CLI to create CodeQL packs, add dependencies to packs, and install or update dependencies. You can also publish and download CodeQL packs using the pack command. For more information, see “Publishing and using CodeQL packs.”

For more information about compatibility between published query packs and different CodeQL releases, see “About CodeQL pack compatibility.”

Creating a CodeQL pack

You can create a CodeQL pack by running the following command from the checkout root of your project:

codeql pack init <scope>/<pack>

You must specify:

  • <scope>: the name of the GitHub organization or user account that you will publish to.

  • <pack>: the name for the pack that you are creating.

The codeql pack init command creates the directory structure and configuration files for a CodeQL pack. By default, the command creates a query pack. If you want to create a library pack, you must edit the qlpack.yml file to explicitly declare the file as a library pack by including the library:true property.

Modifying an existing legacy QL pack to create a CodeQL pack

If you already have a qlpack.yml file, you can edit it manually to convert it into a CodeQL pack.

  1. Edit the name property so that it matches the format <scope>/<name>, where <scope> is the name of the GitHub organization or user account that you will publish to.

  2. In the qlpack.yml file, include a version property with a semver identifier, as well as an optional dependencies block.

  3. Migrate the list of dependencies in libraryPathDependencies to the dependencies block. Specify the version range for each dependency. If the range is unimportant, or you are unsure of compatibility, you can specify "\*", which indicates that any version is acceptable and will default to the latest version when you run codeql pack install.

For more information about the properties, see “About CodeQL packs.”

Adding and installing dependencies to a CodeQL pack

You can add dependencies on CodeQL packs using the command codeql pack add. You must specify the scope, name, and (optionally) a compatible version range.

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

If you don’t specify a version range, the latest version will be added. Otherwise, the latest version that satisfies the requested range will be added.

This command updates the qlpack.yml file with the requested dependencies and downloads them into the package cache. Please note that this command will reformat the file and remove all comments.

You can also manually edit the qlpack.yml file to include dependencies and install the dependencies with the command:

codeql pack install

This command downloads all dependencies to the shared cache on the local disk.

Notes:

  • Running the codeql pack add and codeql pack install commands will generate or update the codeql-pack.lock.yml file. This file should be checked-in to version control. The codeql-pack.lock.yml file contains the precise version numbers used by the pack. For more information, see “About codeql-pack.lock.yml files.”

  • By default codeql pack install will install dependencies from the Container registry on GitHub.com. You can install dependencies from a GitHub Enterprise Server Container registry by creating a qlconfig.yml file. For more information, see “Publishing and using CodeQL packs.”

Customizing a downloaded CodeQL pack

The recommended way to experiment with changes to a pack is to clone the repository containing its source code.

If no source repository is available and you need to base modifications on a pack downloaded from the Container registry, be aware that these packs are not intended to be modified or customized after downloading, and their format may change in the future without much notice. We recommend taking the following steps after downloading a pack if you need to modify the content:

  • Change the pack name in qlpack.yml so you avoid confusion with results from the unmodified pack.

  • Remove all files named *.qlx anywhere in the unpacked directory structure. These files contain precompiled versions of the queries, and in some situations CodeQL will use them in preference to the QL source you have modified.