docs/content/github/finding-security-vulnerabilities-and-errors-in-your-code/running-code-scanning-in-your-ci-system.md

title, shortTitle, intro, product, versions

title	shortTitle	intro	product	versions
Running code scanning in your CI system	Running in your CI	If you use a third-party continuous integration system, you can integrate {{ site.data.variables.product.prodname_codeql }} {{ site.data.variables.product.prodname_code_scanning }} into this system using the {{ site.data.variables.product.prodname_codeql_runner }}.	{{ site.data.reusables.gated-features.code-scanning }}	free-pro-team enterprise-server * >=2.22

{{ site.data.reusables.code-scanning.beta }} {{ site.data.reusables.code-scanning.enterprise-enable-code-scanning }}

About the {{ site.data.variables.product.prodname_codeql_runner }}

{{ site.data.reusables.code-scanning.about-code-scanning }} For information, see "About {{ site.data.variables.product.prodname_code_scanning }}."

You can use the {{ site.data.variables.product.prodname_codeql_runner }} to run {{ site.data.variables.product.prodname_code_scanning }} on code that you're processing in a third-party continuous integration (CI) system. Alternatively, you can use {{ site.data.variables.product.prodname_actions }} to run {{ site.data.variables.product.prodname_code_scanning }} on {{ site.data.variables.product.product_location }}. For information, see "Enabling {{ site.data.variables.product.prodname_code_scanning }} for a repository."

The {{ site.data.variables.product.prodname_codeql_runner }} is a command-line tool that runs {{ site.data.variables.product.prodname_codeql }} analysis on a checkout of a {{ site.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 {{ site.data.variables.product.product_location }}. These results are displayed as {{ site.data.variables.product.prodname_code_scanning }} alerts in the repository.

{{ site.data.reusables.code-scanning.codeql-runner-license }}

Downloading the {{ site.data.variables.product.prodname_codeql_runner }}

You can download the {{ site.data.variables.product.prodname_codeql_runner }} from https://github.com/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

Adding the {{ site.data.variables.product.prodname_codeql_runner }} to your CI system

Once you have downloaded the {{ site.data.variables.product.prodname_codeql_runner }} and verified that it can be executed, you should make the runner available to each CI server that you intend to use for {{ site.data.variables.product.prodname_code_scanning }}. In addition to this, each CI server also needs:

• A {{ site.data.variables.product.prodname_github_apps }} or personal access token for the {{ site.data.variables.product.prodname_codeql_runner }} to use. For private repositories the token must have the repo scope. For public the token needs only the public_repo and repo:security_events scopes. For information, see "Building {{ site.data.variables.product.prodname_github_apps }}" and "Creating a personal access token."
• Access to the {{ site.data.variables.product.prodname_codeql }} bundle associated with this release of the {{ site.data.variables.product.prodname_codeql_runner }}. This package contains the {{ site.data.variables.product.prodname_codeql }} CLI, queries, and libraries needed for {{ site.data.variables.product.prodname_codeql }} analysis. For information, see "{{ site.data.variables.product.prodname_codeql }} CLI."

The options for providing access to the {{ site.data.variables.product.prodname_codeql }} bundle are:

1. Allow the CI servers access to {{ site.data.variables.product.prodname_dotcom_the_website }} so that the {{ site.data.variables.product.prodname_codeql_runner }} can download the bundle automatically.
2. Manually download/extract the bundle, store it with other central resources, and use the --codeql-path flag to specify the location of the bundle in calls to initialize the {{ site.data.variables.product.prodname_codeql_runner }}. {% if currentVersion != "free-pro-team@latest" %}
3. You can mirror the github/codeql-action repository on {{ site.data.variables.product.product_location }}. Unless you specify the --codeql-path flag, the runner automatically checks for the bundle in this location and on {{ site.data.variables.product.prodname_dotcom_the_website }}.{% endif %}

Calling the {{ site.data.variables.product.prodname_codeql_runner }}

You should call the {{ site.data.variables.product.prodname_codeql_runner }} from the checkout location of the repository you want to analyze. The two main commands are:

1. init required to initialize the runner and create a {{ site.data.variables.product.prodname_codeql }} database for each language to be analyzed. These databases are populated and analyzed by subsequent commands.
2. analyze required to populate the {{ site.data.variables.product.prodname_codeql }} databases, analyze them, and upload results to {{ site.data.variables.product.product_location }}.

For both commands, you must specify the URL of {{ site.data.variables.product.product_location }}, the repository OWNER/NAME, and the 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 on {{ site.data.variables.product.prodname_dotcom_the_website}}{% if currentVersion != "free-pro-team@latest" %} or mirrored on {{ site.data.variables.product.product_location }}{% endif %}.

You can configure where the {{ site.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 {{ site.data.variables.product.prodname_code_scanning }} in your CI system."

Basic example

This example runs {{ site.data.variables.product.prodname_codeql }} analysis on a Linux CI server for the octo-org/example-repo repository hosted on {{ site.data.variables.command_line.git_url_example }}. The process is very simple because the repository contains only languages that can be analyzed by {{ site.data.variables.product.prodname_codeql }} directly, without being built (that is, Go, JavaScript, Python, and TypeScript).

1. Check out the repository to analyze.

2. Move into the directory where the repository is checked out.

3. Initialize the {{ site.data.variables.product.prodname_codeql_runner }} and create {{ site.data.variables.product.prodname_codeql }} databases for the languages detected.

   $ /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo
       --github-url {{ site.data.variables.command_line.git_url_example }} --github-auth TOKEN
   > Cleaning temp directory /srv/checkout/example-repo/codeql-runner
   > ...
   > Created CodeQL database at /srv/checkout/example-repo/codeql-runner/codeql_databases/javascript.
   

4. Populate the {{ site.data.variables.product.prodname_codeql_runner }} databases, analyze them, and upload the results to {{ site.data.variables.product.product_name }}.

   $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
       --github-url {{ site.data.variables.command_line.git_url_example }} --github-auth TOKEN
       --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/main
   > Finalizing database creation
   > ...
   > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
   > Successfully uploaded results
   

The server has access to download the {{ site.data.variables.product.prodname_codeql }} bundle directly from the github/codeql-action repository on {{ site.data.variables.product.prodname_dotcom_the_website}}{% if currentVersion != "free-pro-team@latest" %} or mirrored on {{ site.data.variables.product.product_location }}{% endif %}, so there is no need to use the --codeql-path flag. When the analysis is complete, the {{ site.data.variables.product.prodname_codeql_runner }} uploads the results to the {{ site.data.variables.product.prodname_code_scanning }} view. For more information, see "Managing alerts from {{ site.data.variables.product.prodname_code_scanning }}."

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 {{ site.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.

1. Check out the repository to analyze.

2. Move into the directory where the repository is checked out.

3. Initialize the {{ site.data.variables.product.prodname_codeql_runner }} and create {{ site.data.variables.product.prodname_codeql }} databases for the languages detected.

   $ /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo-2
       --github-url {{ site.data.variables.command_line.git_url_example }} --github-auth TOKEN
   > 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 the build can be traced, for example by running "
     . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
   

4. Run the script generated by the init action to set up the environment to monitor the build.

   $ . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh
   

5. Build the code.

6. Populate the {{ site.data.variables.product.prodname_codeql }} databases, analyze them, and upload the results to GitHub.

   $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo-2
       --github-url {{ site.data.variables.command_line.git_url_example }} --github-auth TOKEN
       --commit ae7b655ef30b50fb726ae7b3daa79571a39d194d --ref refs/heads/main
   > Finalizing database creation
   > ...
   > POST /repos/octo-org/example-repo-2/code-scanning/sarifs - 202 in 573ms
   > Successfully uploaded results
   

{% note %}

Note: If you use a containerized build, you need to run the {{ site.data.variables.product.prodname_codeql_runner }} in the container where your build task takes place.

{% endnote %}

Further reading

• "Configuring {{ site.data.variables.product.prodname_code_scanning }} in your CI system"
• "Troubleshooting {{ site.data.variables.product.prodname_code_scanning }} in your CI system"