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."
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.
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. 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>is the folder where you extracted the CodeQL CLI bundle.
- By adding
PATH, so that you can run the executable as just
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 languagesif
/extraction-root/codeqlis on the
/extraction-root/codeql/codeql resolve languagesotherwise.
Example of successful output:
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.
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."
You call the CodeQL CLI to analyze the codebase in three steps:
- Create a CodeQL database to represent a single programming language in the repository using:
codeql database create
- Run queries to analyze the CodeQL database and summarize the results in a SARIF file using:
codeql database analyze
- 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
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."
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.
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.
codeql database createfrom 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.
|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.|
|Specify the identifier for the language to create a database for, one of: |
|Optional. Use if you run the CLI outside the checkout root of the repository. By default, the |
|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 |
For more information, see Creating CodeQL databases in the documentation for the CodeQL CLI.
For more information and examples, see Creating CodeQL databases in the documentation for the CodeQL CLI.
- Create a CodeQL database (see above).
codeql database analyzeon the database and specify which queries to use.
codeql database analyze <database> --format=<format> \ --output=<output> <queries>
|Specify the path for the directory that contains the CodeQL database to analyze.|
|Specify the queries to run. To run the standard queries used for code scanning, use: |
|Specify the format for the results file generated by the command. For upload to GitHub this should be: |
|Specify where to save the SARIF results file.|
|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 |
|Optional. Use if you want to use more than one thread to run queries. The default value is |
For more information, see Analyzing databases with the CodeQL CLI in the documentation for the CodeQL CLI.
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
- Saving the secret in the environment variable
GITHUB_TOKENand running the CLI without including the
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
echo "$UPLOAD_TOKEN" | codeql github upload-results --repository=<repository-name> \ --ref=<ref> --commit=<commit> --sarif=<file> \ --github-auth-stdin
|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."|
|Specify the name of the |
|Specify the full SHA of the commit you analyzed.|
|Specify the SARIF file to load.|
|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 |
For more information, see github upload-results in the documentation for the CodeQL CLI.
$ 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."