Note: The CodeQL package management functionality, including CodeQL packs, is currently available as a beta release and is subject to change. During the beta release, CodeQL packs are available only using GitHub Packages - the Container registry. To use this beta functionality, install the latest version of the CodeQL CLI bundle from: https://github.com/github/codeql-action/releases.
Note: This article describes the features available with the CodeQL CLI 2.12.7 bundle included in the initial release of GitHub Enterprise Server 3.9.
If your site administrator has updated your CodeQL CLI version to a newer release, please see the GitHub Enterprise Cloud version of this article for information on the latest features.
CodeQL packs are used to create, share, depend on, and run CodeQL queries and libraries. CodeQL packs contain queries, library files, query suites, and metadata. 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 "Publishing and using CodeQL packs."
The standard CodeQL packages for all supported languages are published in the Container registry. The CodeQL repository contains source files for the standard CodeQL packs for all supported languages. The core query packs, which are included in the CodeQL CLI bundle, but you can otherwise download, are:
A CodeQL pack must contain a file called
qlpack.yml in its root directory. In the
qlpack.yml file, the
name: field must have a value that follows the format of
<scope> is the GitHub organization or user account that the pack will be published to and
<pack> is the name of the pack. Additionally, query packs and library packs with CodeQL tests contain a
codeql-pack.lock.yml file that contains the resolved dependencies of the pack. This file is generated during a call to the
codeql pack install command, is not meant to be edited by hand, and should be added to your version control system.
The other files and directories within the pack should be logically organized. For example, typically:
Queries are organized into directories for specific categories.
Queries for specific products, libraries, and frameworks are organized into their own top-level directories.
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.
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
If you already have a
qlpack.yml file, you can edit it manually to convert it into a CodeQL pack.
nameproperty so that it matches the format
<scope>is the name of the GitHub organization or user account that you will publish to.
qlpack.ymlfile, include a
versionproperty with a semver identifier, as well as an optional
Migrate the list of dependencies in
dependenciesblock. 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 "Customizing analysis with CodeQL packs."
Note: This is only supported for CodeQL query and library packs.
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.
codeql pack addand
codeql pack installcommands will generate or update the
codeql-pack.lock.ymlfile. This file should be checked-in to version control. The
codeql-pack.lock.ymlfile contains the precise version numbers used by the pack. For more information, see "About codeql-pack.lock.yml files."
codeql pack installwill install dependencies from the Container registry on GitHub.com. You can install dependencies from a GitHub Enterprise Server Container registry by creating a
qlconfig.ymlfile. For more information, see "Publishing and using CodeQL packs" in the GitHub Enterprise Server documentation.
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.ymlso you avoid confusion with results from the unmodified pack.
Remove all files named
*.qlxanywhere 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.