14 KiB
title, shortTitle, intro, product, redirect_from, versions, type, topics
| title | shortTitle | intro | product | redirect_from | versions | type | topics | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Running CodeQL runner in your CI system | Running CodeQL runner | You can use the {% data variables.product.prodname_codeql_runner %} to perform {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} in a third-party continuous integration system. | {% data reusables.gated-features.code-scanning %} |
|
|
how_to |
|
{% data reusables.code-scanning.beta-codeql-runner %} {% data reusables.code-scanning.beta %} {% data reusables.code-scanning.enterprise-enable-code-scanning %}
About the {% data variables.product.prodname_codeql_runner %}
The {% data variables.product.prodname_codeql_runner %} is a tool you can use to run {% data variables.product.prodname_code_scanning %} on code that you're processing in a third-party continuous integration (CI) system. {% data reusables.code-scanning.about-code-scanning %} For information, see "About {% data variables.product.prodname_code_scanning %}."
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" or currentVersion == "github-ae@next" %} In many cases it is easier to set up {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} using the {% data variables.product.prodname_codeql_cli %} directly in your CI system. The runner is more complex and less forgiving to set up than the CLI, and is recommended only if you need its capability to analyze multiple compiled languages with a single build, or to integrate with complex build processes. For more information, see "About CodeQL code scanning in your CI system". {% endif %}
Alternatively, you can use {% data variables.product.prodname_actions %} to run {% data variables.product.prodname_code_scanning %} within {% data variables.product.product_name %}. For information, see "Setting up {% data variables.product.prodname_code_scanning %} for a repository."
The {% data variables.product.prodname_codeql_runner %} is a command-line tool that runs {% data variables.product.prodname_codeql %} analysis on a checkout of a {% data variables.product.prodname_dotcom %} repository. You add the runner to your third-party system, then call the runner to analyze code and upload the results to {% data variables.product.product_name %}. These results are displayed as {% data variables.product.prodname_code_scanning %} alerts in the repository.
{% note %}
Note: {% if currentVersion == "free-pro-team@latest" %}
- The {% data variables.product.prodname_codeql_runner %} uses the {% data variables.product.prodname_codeql %} CLI to analyze code and therefore has the same license conditions. It's free to use on public repositories that are maintained on {% data variables.product.prodname_dotcom_the_website %}, and available to use on private repositories that are owned by customers with an {% data variables.product.prodname_advanced_security %} license. For information, see "{% data variables.product.product_name %} {% data variables.product.prodname_codeql %} Terms and Conditions" and "{% data variables.product.prodname_codeql %} CLI." {% else %}
- The {% data variables.product.prodname_codeql_runner %} is available to customers with an {% data variables.product.prodname_advanced_security %} license. {% endif %} {% if currentVersion ver_lt "enterprise-server@3.1" or currentVersion == "github-ae@latest" %}
- The {% data variables.product.prodname_codeql_runner %} shouldn't be confused with the {% data variables.product.prodname_codeql %} CLI. The {% data variables.product.prodname_codeql %} CLI is a command-line interface that lets you create {% data variables.product.prodname_codeql %} databases for security research and run {% data variables.product.prodname_codeql %} queries. For more information, see "{% data variables.product.prodname_codeql_cli %}." {% endif %} {% endnote %}
Downloading the {% data variables.product.prodname_codeql_runner %}
You can download the {% data variables.product.prodname_codeql_runner %} from https://{% if currentVersion == "free-pro-team@latest" %}github.com{% else %}HOSTNAME{% endif %}/github/codeql-action/releases. On some operating systems, you may need to change permissions for the downloaded file before you can run it.
On Linux:
chmod +x codeql-runner-linux
On macOS:
chmod +x codeql-runner-macos
sudo xattr -d com.apple.quarantine codeql-runner-macos
On Windows, the codeql-runner-win.exe file usually requires no change to permissions.
Adding the {% data variables.product.prodname_codeql_runner %} to your CI system
Once you download the {% data variables.product.prodname_codeql_runner %} and verify that it can be executed, you should make the runner available to each CI server that you intend to use for {% data variables.product.prodname_code_scanning %}. For example, you might configure each server to copy the runner from a central, internal location. Alternatively, you could use the REST API to get the runner directly from {% data variables.product.prodname_dotcom %}, for example:
wget https://{% if currentVersion == "free-pro-team@latest" %}github.com{% else %}<em>HOSTNAME</em>{% endif %}/github/codeql-action/releases/latest/download/codeql-runner-linux
chmod +x codeql-runner-linux
In addition to this, each CI server also needs:
- A {% data variables.product.prodname_github_app %} or personal access token for the {% data variables.product.prodname_codeql_runner %} to use. You must use an access token with the
reposcope, or a {% data variables.product.prodname_github_app %} with thesecurity_eventswrite permission, andmetadataandcontentsread permissions. For information, see "Building {% data variables.product.prodname_github_apps %}" and "Creating a personal access token." - Access to the {% data variables.product.prodname_codeql %} bundle associated with this release of the {% data variables.product.prodname_codeql_runner %}. This package contains queries and libraries needed for {% data variables.product.prodname_codeql %} analysis, plus the {% data variables.product.prodname_codeql %} CLI, which is used internally by the runner. For information, see "{% data variables.product.prodname_codeql %} CLI."
The options for providing access to the {% data variables.product.prodname_codeql %} bundle are:
- Allow the CI servers access to https://{% if currentVersion == "free-pro-team@latest" %}github.com{% else %}HOSTNAME{% endif %}/github/codeql-action so that the {% data variables.product.prodname_codeql_runner %} can download the bundle automatically.
- Manually download/extract the bundle, store it with other central resources, and use the
--codeql-pathflag to specify the location of the bundle in calls to initialize the {% data variables.product.prodname_codeql_runner %}.
Calling the {% data variables.product.prodname_codeql_runner %}
You should call the {% data variables.product.prodname_codeql_runner %} from the checkout location of the repository you want to analyze. The two main commands are:
initrequired to initialize the runner and create a {% data variables.product.prodname_codeql %} database for each language to be analyzed. These databases are populated and analyzed by subsequent commands.analyzerequired to populate the {% data variables.product.prodname_codeql %} databases, analyze them, and upload results to {% data variables.product.product_name %}.
For both commands, you must specify the URL of {% data variables.product.product_name %}, the repository OWNER/NAME, and the {% data variables.product.prodname_github_apps %} or personal access token to use for authentication. You also need to specify the location of the CodeQL bundle, unless the CI server has access to download it directly from the github/codeql-action repository.
You can configure where the {% data variables.product.prodname_codeql_runner %} stores the CodeQL bundle for future analysis on a server using the --tools-dir flag and where it stores temporary files during analysis using --temp-dir.
To view the command-line reference for the runner, use the -h flag. For example, to list all commands run: codeql-runner-OS -h, or to list all the flags available for the init command run: codeql-runner-OS init -h (where OS varies according to the executable that you are using). For more information, see "Configuring {% data variables.product.prodname_code_scanning %} in your CI system."
{% data reusables.code-scanning.upload-sarif-alert-limit %}
Basic example
This example runs {% data variables.product.prodname_codeql %} analysis on a Linux CI server for the octo-org/example-repo repository hosted on {% data variables.command_line.git_url_example %}. The process is very simple because the repository contains only languages that can be analyzed by {% data variables.product.prodname_codeql %} directly, without being built (that is, Go, JavaScript, Python, and TypeScript).
In this example, the server has access to download the {% data variables.product.prodname_codeql %} bundle directly from the github/codeql-action repository, so there is no need to use the --codeql-path flag.
- Check out the repository to analyze.
- Move into the directory where the repository is checked out.
- Initialize the {% data variables.product.prodname_codeql_runner %} and create {% data variables.product.prodname_codeql %} databases for the languages detected.
{% if currentVersion ver_lt "enterprise-server@3.1" %}
$ /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo
--github-url {% data variables.command_line.git_url_example %} --github-auth TOKEN
{% else %}
shell $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo --github-url {% data variables.command_line.git_url_example %} --github-auth-stdin > Cleaning temp directory /srv/checkout/example-repo/codeql-runner > ... > Created CodeQL database at /srv/checkout/example-repo/codeql-runner/codeql_databases/javascript.
{% endif %}
{% data reusables.code-scanning.codeql-runner-analyze-example %}
Compiled language example
This example is similar to the previous example, however this time the repository has code in C/C++, C#, or Java. To create a {% data variables.product.prodname_codeql %} database for these languages, the CLI needs to monitor the build. At the end of the initialization process, the runner reports the command you need to set up the environment before building the code. You need to run this command, before calling the normal CI build process, and then running the analyze command.
- Check out the repository to analyze.
- Move into the directory where the repository is checked out.
- Initialize the {% data variables.product.prodname_codeql_runner %} and create {% data variables.product.prodname_codeql %} databases for the languages detected. {% if currentVersion ver_lt "enterprise-server@3.1" %}
$ /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo-2
--github-url {% data variables.command_line.git_url_example %} --github-auth TOKEN
{% else %}
shell $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo-2 --github-url {% data variables.command_line.git_url_example %} --github-auth-stdin > Cleaning temp directory /srv/checkout/example-repo-2/codeql-runner > ... > CodeQL environment output to "/srv/checkout/example-repo-2/codeql-runner/codeql-env.json" and "/srv/checkout/example-repo-2/codeql-runner/codeql-env.sh". Please export these variables to future processes so that CodeQL can monitor the build, for example by running ". /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
{% endif %}
-
Source the script generated by the
initaction to set up the environment to monitor the build. Note the leading dot and space in the following code snippet.$ . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh -
Build the code. On macOS, you need to prefix the build command with the environment variable
$CODEQL_RUNNER. For more information, see "Troubleshooting {% data variables.product.prodname_codeql_runner %} in your CI system."
{% data reusables.code-scanning.codeql-runner-analyze-example %}
{% note %}
Note: If you use a containerized build, you need to run the {% data variables.product.prodname_codeql_runner %} in the container where your build task takes place.
{% endnote %}