Installing CodeQL CLI in your CI system

You can install the CodeQL CLI and use it to perform CodeQL 代码扫描 in a third-party continuous integration system.

代码扫描 适用于所有公共仓库以及启用了 GitHub Advanced Security 的组织拥有的私有仓库。 更多信息请参阅“关于 GitHub Advanced Security”。

About using the CodeQL CLI for 代码扫描

You can use the CodeQL CLI to run 代码扫描 on code that you're processing in a third-party continuous integration (CI) system. 代码扫描 是一项功能,可用于分析 GitHub 仓库中的代码,以查找安全漏洞和编码错误。 分析发现的任何问题都显示在 GitHub 中。 For information, see "About 代码扫描 with CodeQL."

CodeQL CLI 是一个可用来分析代码的独立产品。 其主要用途是生成代码空间的数据库表示形式,即 CodeQL 数据库。 数据库准备就绪后,您可以进行交互式查询,或者运行一系列查询以生成一组 SARIF 格式的结果,然后将结果上传到 GitHub.com。

Alternatively, you can use GitHub Actions to run 代码扫描 within GitHub. For information about 代码扫描 using actions, see "Setting up 代码扫描 for a repository." For an overview of the options for CI systems, see "About CodeQL 代码扫描 in your CI system".

注: CodeQL CLI 可免费用于 GitHub.com 上维护的公共仓库,也可用于具有 Advanced Security 许可证的客户所拥有的私有仓库。 有关信息请参阅“GitHub CodeQL 条款和条件”和“CodeQL CLI”。

Downloading the CodeQL CLI

You should download the CodeQL bundle from https://github.com/github/codeql-action/releases. The bundle contains:

  • CodeQL CLI product
  • A compatible version of the queries and libraries from https://github.com/github/codeql
  • Precompiled versions of all the queries included in the bundle

You should always use the CodeQL bundle as this ensures compatibility and also gives much better performance than a separate download of the CodeQL CLI and checkout of the CodeQL queries. If you will only be running the CLI on one specific platform, download the appropriate codeql-bundle-PLATFORM.tar.gz file. Alternatively, you can download codeql-bundle.tar.gz, which contains the CLI for all supported platforms.

Note: The CodeQL package management functionality, including CodeQL packs, is currently in beta and subject to change.

Setting up the CodeQL CLI in your CI system

You need to make the full contents of the CodeQL CLI bundle available to every CI server that you want to run CodeQL 代码扫描 analysis on. For example, you might configure each server to copy the bundle from a central, internal location and extract it. Alternatively, you could use the REST API to get the bundle directly from GitHub, ensuring that you benefit from the latest improvements to queries. Updates to the CodeQL CLI are released every 2-3 weeks. For example:

$ wget https://github.com/github/codeql-action/releases/latest/download/codeql-bundle-linux64.tar.gz
$ tar -xvzf ../codeql-bundle-linux64.tar.gz

After you extract the CodeQL CLI bundle, you can run the codeql executable on the server:

  • By executing /<extraction-root>/codeql/codeql, where <extraction-root> is the folder where you extracted the CodeQL CLI bundle.
  • By adding /<extraction-root>/codeql to your PATH, so that you can run the executable as just codeql.

Testing the CodeQL CLI set up

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

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

Extract from successful output:

codeql-cpp (/<extraction-root>/codeql/qlpacks/codeql-cpp)
codeql-cpp-examples (/<extraction-root>/codeql/qlpacks/codeql-cpp-examples)
codeql-cpp-upgrades (/<extraction-root>/codeql/qlpacks/codeql-cpp-upgrades)
codeql-csharp (/<extraction-root>/codeql/qlpacks/codeql-csharp)
codeql-csharp-examples (/<extraction-root>/codeql/qlpacks/codeql-csharp-examples)
codeql-csharp-upgrades (/<extraction-root>/codeql/qlpacks/codeql-csharp-upgrades)
codeql-go (/<extraction-root>/codeql/qlpacks/codeql-go)
codeql-go-examples (/<extraction-root>/codeql/qlpacks/codeql-go-examples)
codeql-go-upgrades (/<extraction-root>/codeql/qlpacks/codeql-go-upgrades)
codeql-java (/<extraction-root>/codeql/qlpacks/codeql-java)
codeql-java-examples (/<extraction-root>/codeql/qlpacks/codeql-java-examples)
codeql-java-upgrades (/<extraction-root>/codeql/qlpacks/codeql-java-upgrades)
codeql-javascript (/<extraction-root>/codeql/qlpacks/codeql-javascript)
codeql-javascript-examples (/<extraction-root>/codeql/qlpacks/codeql-javascript-examples)
codeql-javascript-upgrades (/<extraction-root>/codeql/qlpacks/codeql-javascript-upgrades)
codeql-python (/<extraction-root>/codeql/qlpacks/codeql-python)
codeql-python-examples (/<extraction-root>/codeql/qlpacks/codeql-python-examples)
codeql-python-upgrades (/<extraction-root>/codeql/qlpacks/codeql-python-upgrades)
...

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 above as <extraction root>, unless you are using a checkout of github/codeql. 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.

Generating a token for authentication with GitHub

Each CI server needs a GitHub 应用程序 or personal access token for the CodeQL CLI to use to upload results to GitHub. You must use an access token or a GitHub 应用程序 with the security_events write permission. If CI servers already use a token with this scope to checkout repositories from GitHub, you could potentially allow the CodeQL CLI to use the same token. Otherwise, you should create a new token with the security_events write permission and add this to the CI system's secret store. For information, see "Building GitHub 应用程序" and "Creating a personal access token."

Next steps

You're now ready to configure the CI system to run CodeQL analysis, generate results, and upload them to GitHub where the results will be matched to a branch or pull request and displayed as 代码扫描 alerts. For detailed information, see "Configuring CodeQL CLI in your CI system."

此文档对您有帮助吗?

隐私政策

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或者, 了解如何参与。