Setting up the CodeQL CLI

To get started with the CodeQL CLI, you need to download and set up the CLI so that it can access the tools and libraries required to create and analyze databases.

谁可以使用此功能？

CodeQL 可用于以下存储库类型：

在本文中

Setting up the CodeQL CLI

注意

本文介绍了 GitHub Enterprise Server 3.20 的初始发行版中包含的 CodeQL CLI 2.23.9 捆绑包中可用的功能。

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

To run CodeQL commands, you need to set up the CodeQL CLI so that it can access the tools, queries, and libraries required to create and analyze databases.

The CodeQL CLI supports a range of use cases and directory structures. This article walks through a simple setup that works for most users and environments.

If you plan to use the CodeQL CLI for security research or to test or contribute queries, you may need a more advanced setup. For more information, see 关于 CodeQL CLI.

Before you begin

If you are using macOS on Apple Silicon (for example, Apple M1), ensure that the Xcode command-line developer tools and Rosetta 2 are installed.

注意

The CodeQL CLI is currently not compatible with non-glibc Linux distributions such as (muslc-based) Alpine Linux.

1. Download the CodeQL CLI tar archive

CodeQL CLI 下载包是一个 zip 存档，其中包含工具、脚本和特定于 CodeQL 的各种文件。 如果没有 GitHub Enterprise 许可证，那么下载此存档即表示你同意 GitHub CodeQL 条款和条件。

应从 https://github.com/github/codeql-action/releases 下载 CodeQL 包。 该捆绑包中包含：

注意

对于 GitHub Enterprise Server 3.20，我们建议使用 CodeQL CLI 版本 2.23.9。

应该始终使用 CodeQL 捆绑包。 这样可以确保兼容性，并且比单独下载 CodeQL CLI 和检出 CodeQL 查询提供更好的性能。 如果只在一个特定平台上运行 CLI，请下载相应的 codeql-bundle-PLATFORM.tar.zst 文件。 此外，也可以下载包含所有受支持平台的 CLI 的 codeql-bundle.tar.zst。

捆绑包还有 tar.gz 变体，这些变体与 tar.zst 变体相同，但使用效率较低的 gzip 算法进行压缩。 下载 tar.gz 变体的唯一原因是使用不支持 Zstandard 压缩算法的较旧解压缩工具。

2. Extract the CodeQL CLI tar archive

Extract the CodeQL CLI tar archive to a directory of your choosing.

Optional: Make the CodeQL CLI available in your CI system

If you plan to run CodeQL code scanning analysis in a CI system, ensure that the full contents of the CodeQL CLI bundle are available to every CI server that will run analysis.

For example, you can:

  • Copy the bundle from a central internal location and extract it on each server, or
  • Use the REST API to download the bundle directly from GitHub, ensuring that you receive the latest improvements to queries. For more information, see 发布和发布资产的 REST API 终结点.

3. Launch codeql

提取后，可以通过多种方式运行 codeql 可执行文件来运行 CodeQL 进程：

  • 通过执行 <extraction-root>/codeql/codeql，其中 <extraction-root> 是要在其中提取 CodeQL CLI 包的文件夹。
  • 通过将 <extraction-root>/codeql 添加到 PATH，这样就可以像 codeql 一样运行可执行文件。

此时，可以执行 CodeQL 命令。 有关 CodeQL CLI 命令的完整列表，请参阅“CodeQL CLI 命令手册”。

注意

If you add codeql to your PATH, it can be accessed by CodeQL for Visual Studio Code to compile and run queries. For more information about configuring VS Code to access the CodeQL CLI, see Managing the CodeQL CLI in the VS Code extension.

Testing the CodeQL CLI configuration

After you extract the CodeQL CLI bundle, you can run the following command to verify that the CLI is correctly configured to create and analyze databases:

  • codeql resolve packs if /<extraction root>/codeql is on the PATH.
  • /<extraction root>/codeql/codeql resolve packs otherwise.

If successful, you should see output similar to the extract below:

Searching directories specified by `--additional-packs`. All directories have equal priority.
  Searching in:
    No packs were found at this location.
Searching directories specified by `--search-path`. Directories are searched in order.
Searching the root of the CodeQL distribution.
  Searching in:
      <extraction root>
    The following packs were found:
      codeql/java-all@<version>: (library) <extraction root>/qlpacks/codeql/javat-all/<version>/qlpack.yml
      codeql/java-queries@<version>: (query) <extraction root>/qlpacks/codeql/java-queries/<version>/qlpack.yml
      codeql/javascript-all@<version>: (library) <extraction root>/qlpacks/codeql/javascript-all/<version>/qlpack.yml
      codeql/javascript-queries@<version>: (query) <extraction root>/qlpacks/codeql/javascript-queries/<version>/qlpack.yml
      codeql/swift-all@<version>: (library) <extraction root>/qlpacks/codeql/swift-all/<version>/qlpack.yml
      codeql/swift-queries@<version>: (query) <extraction root>/qlpacks/codeql/swift-queries/<version>/qlpack.yml
...

The results have been truncated for brevity. The actual results will be longer and more detailed.

You should check that the output contains the expected languages and also that the directory location for the qlpack files is correct. The location should be within the extracted CodeQL CLI bundle, shown in the earlier example as <extraction root>. If the CodeQL CLI is unable to locate the qlpacks for the expected languages, check that you downloaded the CodeQL bundle and not a standalone copy of the CodeQL CLI.

You can also run codeql resolve languages to show which languages are available for database creation. This will list the languages supported by default in your CodeQL CLI package.

Optionally, you can download some CodeQL packs containing pre-compiled queries you would like to run. For more information, see 使用 CodeQL 包自定义分析.

The codeql resolve packs command is useful for diagnosing problems when the CodeQL CLI is unable to locate query packs that you expect to be available for analysis.

注意

The codeql resolve packs command is available in the CodeQL CLI versions 2.19.0 and later. For earlier versions of the CLI, you should run the codeql resolve qlpacks command, which produces similar, but less detailed output.

Next steps

To learn how to prepare your code to be analyzed by the CodeQL CLI, see 为 CodeQL 分析准备代码.