Running CodeQL CLI in your CI system

You can use the CodeQL CLI to perform CodeQL code scanning in a third-party continuous integration system.

Code scanning is available for all public repositories, and for private repositories owned by organizations where GitHub Advanced Security is enabled. Weitere Informationen findest Du unter „Informationen zu GitHub Advanced Security“.

Informationen zu CodeQL CLI

You can use the CodeQL CLI to run code scanning on code that you're processing in a third-party continuous integration (CI) system. Code scanning is a feature that you use to analyze the code in a GitHub repository to find security vulnerabilities and coding errors. Any problems identified by the analysis are shown in GitHub. For information, see "About code scanning."

The CodeQL CLI is a standalone product that you can use to analyze code. Its main purpose is to generate a database representation of a codebase, a CodeQL database. Once the database is ready, you can query it interactively, or run a suite of queries to generate a set of results in SARIF format and upload the results to GitHub.

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

Note: The CodeQL CLI is free to use on public repositories that are maintained on GitHub.com, and available to use on private repositories that are owned by customers with an Advanced Security license. For information, see "GitHub CodeQL Terms and Conditions" and "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.

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 code scanning 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. Ein Beispiel:

$ 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 languages if /extraction-root/codeql is on the PATH.
  • /extraction-root/codeql/codeql resolve languages otherwise.

Example of successful output:

cpp (/extraction-root/codeql/cpp)
csharp (/extraction-root/codeql/csharp)
csv (/extraction-root/codeql/csv)
go (/extraction-root/codeql/go)
html (/extraction-root/codeql/html)
java (/extraction-root/codeql/java)
javascript (/extraction-root/codeql/javascript)
properties (/extraction-root/codeql/properties)
python (/extraction-root/codeql/python)
xml (/extraction-root/codeql/xml)

If the CodeQL CLI is unable to resolve 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 App or personal access token for the CodeQL CLI to use to upload results to GitHub. You must use an access token or a GitHub App 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 Apps" and "Creating a personal access token."

Using the CodeQL CLI to generate data and upload it to GitHub

You call the CodeQL CLI to analyze the codebase in three steps:

  1. Create a CodeQL database to represent a single programming language in the repository using: codeql database create
  2. Run queries to analyze the CodeQL database and summarize the results in a SARIF file using: codeql database analyze
  3. Upload the SARIF file to GitHub where the results are matched to a branch or pull request and displayed as code scanning alerts using: codeql github upload-results

Each command has a few mandatory options with additional options that you can use to modify the behavior of the command. You can display the command-line help for any command using the --help option.

Note: Uploading SARIF data to display as code scanning results in GitHub is supported for organization-owned repositories with GitHub Advanced Security enabled, and public repositories on GitHub.com. For more information, see "Managing security and analysis settings for your repository."

Creating a CodeQL database to analyze

  1. Check out the code that you want to analyze:

    • For a branch checkout the head of the branch that you want to analyze.
    • For a pull request checkout either the head commit of the pull request, or check out a GitHub-generated merge commit of the pull request.
  2. Set up the environment for the codebase, making sure that any dependencies are available. For more information, see Creating databases for non-compiled languages and Creating databases for compiled languages in the documentation for the CodeQL CLI.

  3. Run codeql database create from the checkout root of your repository.

    codeql database create <database> --language=<language-identifier>

    Note: If you use a containerized build, you need to run the CodeQL CLI inside the container where your build task takes place.

Option Erforderlich Beispiel
<database> Specify the name and location of a directory to create for the CodeQL database. The command will fail if you try to overwrite an existing directory.
`--language` Specify the identifier for the language to create a database for, one of: `cpp`, `csharp`, `go`, `java`, `javascript`, and `python` (use javascript to analyze TypeScript code).
`--source-root` Optional. Use if you run the CLI outside the checkout root of the repository. By default, the database create command assumes that the current directory is the root directory for the source files, use this option to specify a different location.
`--command` Optional for compiled languages. Use if you want to override the CLI's automatic build system detection and compilation. Specify the build command or script that invokes the compiler. Commands are run from the current folder or, where it is defined, from `--source-root`. Do not use this option for Python and JavaScript/TypeScript analysis.

For more information, see Creating CodeQL databases in the documentation for the CodeQL CLI.

Basic example
$ codeql database create /codeql-dbs/example-repo --language=javascript \
    --source-root /checkouts/example-repo

> Initializing database at /codeql-dbs/example-repo.
> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd]
    in /checkouts/example-repo.
> [build-stdout] Single-threaded extraction.
> [build-stdout] Extracting
... 
> Finalizing database at /codeql-dbs/example-repo.
> Successfully created database at /codeql-dbs/example-repo.

For more information and examples, see Creating CodeQL databases in the documentation for the CodeQL CLI.

Analyzing a CodeQL database

  1. Create a CodeQL database (see above).
  2. Run codeql database analyze on the database and specify which queries to use.
    codeql database analyze <database> --format=<format> \
        --output=<output>  <queries> 
Option Erforderlich Beispiel
<database> Specify the path for the directory that contains the CodeQL database to analyze.
<queries> Specify the queries to run. To run the standard queries used for code scanning, use: <language>-code-scanning.qls where <language> is the short code for the language of the database. To see the other query suites included in the CodeQL CLI bundle look in /extraction-root/codeql/qlpacks/codeql-<language>/codeql-suites. For information about creating your own query suite, see Creating CodeQL query suites in the documentation for the CodeQL CLI.
`--format` Specify the format for the results file generated by the command. For upload to GitHub this should be: sarif-latest. For more information, see "SARIF support for code scanning."
`--output` Specify where to save the SARIF results file.
--sarif-category Optional. Specify a category to include in the SARIF results file for this analysis. A category can be used to distinguish multiple analyses for the same tool and commit, but performed on different languages or different parts of the code. This value will appear in the <run>.automationId property in SARIF v1, the <run>.automationLogicalId property in SARIF v2, and the <run>.automationDetails.id property in SARIF v2.1.0. |
`--threads` Optional. Use if you want to use more than one thread to run queries. The default value is 1. You can specify more threads to speed up query execution. To set the number of threads to the number of logical processors, specify 0.

For more information, see Analyzing databases with the CodeQL CLI in the documentation for the CodeQL CLI.

Basic example
$ codeql database analyze /codeql-dbs/example-repo  \
    javascript-code-scanning.qls --format=sarif-latest \
    --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/
    codeql-javascript/AngularJS/DisablingSce.ql.
... 
> Shutting down query evaluator.
> Interpreting results.

Uploading results to GitHub

Note: SARIF upload supports a maximum of 5000 results per upload. Any results over this limit are ignored. If a tool generates too many results, you should update the configuration to focus on results for the most important rules or queries.

Before you can upload results to GitHub, you must determine the best way to pass the GitHub App or personal access token you created earlier to the CodeQL CLI (see Generating a token for authentication with GitHub above). We recommend that you review your CI system's guidance on the secure use of the secret store. The CodeQL CLI supports:

  • Passing the token to the CLI via standard input using the --github-auth-stdin option (recommended).
  • Saving the secret in the environment variable GITHUB_TOKEN and running the CLI without including the --github-auth-stdin option.

When you have decided on the most secure and reliable method for your CI server, run codeql github upload-results on the SARIF results file and include --github-auth-stdin unless the token is available in the environment variable GITHUB_TOKEN.

echo "$UPLOAD_TOKEN" | codeql github upload-results --repository=<repository-name> \
      --ref=<ref> --commit=<commit> --sarif=<file> \
      --github-auth-stdin
Option Erforderlich Beispiel
`--repository` Specify the OWNER/NAME of the repository to upload data to. The owner must be an organization within an enterprise that has a license for GitHub Advanced Security and GitHub Advanced Security must be enabled for the repository, unless the repository is public. For more information, see "Managing security and analysis settings for your repository."
`--ref` Specify the name of the ref you checked out and analyzed so that the results can be matched to the correct code. For a branch use: refs/heads/BRANCH-NAME, for the head commit of a pull request use refs/pulls/NUMBER/head, or for the GitHub-generated merge commit of a pull request use refs/pulls/NUMBER/merge.
`--commit` Specify the full SHA of the commit you analyzed.
`--sarif` Specify the SARIF file to load.
`--github-auth-stdin` Optional. Use to pass the CLI the GitHub App or personal access token created for authentication with GitHub's REST API via standard input. This is not needed if the command has access to a GITHUB_TOKEN environment variable set with this token.

For more information, see github upload-results in the documentation for the CodeQL CLI.

Basic example
$ echo $UPLOAD_TOKEN | codeql  github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-auth-stdin

There is no output from this command unless the upload was unsuccessful. The command prompt returns when the upload is complete and data processing has begun. On smaller codebases, you should be able to explore the code scanning alerts in GitHub shortly afterward. Alerts are shown directly in the pull request or on the Security tab for branches, depending on the code that was checked out. For more information, see "Triaging code scanning alerts in pull requests" and "Managing code scanning alerts for your repository."

Weiterführende Informationen

Did this doc help you?Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Oder, learn how to contribute.