Running CodeQL runner in your CI system

You can use the CodeQLランナー 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. 詳しい情報については、「GitHub Advanced Security について」を参照してください。

Note: The CodeQLランナー is being deprecated. Please use the CodeQL CLI version 2.6.2 or greater instead. GitHub Enterprise Server 3.3 will be the final release series that supports the CodeQLランナー. On GitHub Enterprise Cloud, the CodeQLランナー will be supported until March 2022. For more information, see the CodeQL runner deprecation.

About the CodeQLランナー

The CodeQLランナー is a tool you can use to run code scanning on code that you're processing in a third-party continuous integration (CI) system. Code scanning は、開発者が GitHub リポジトリ内のコードを分析して、セキュリティの脆弱性とコーディングエラーを見つけることができる機能です。 分析によって特定されたすべての問題はGitHubに表示されます。 For information, see "About code scanning with CodeQL."

In many cases it is easier to set up CodeQL code scanning using the CodeQL CLI directly in your CI system.

Alternatively, you can use GitHub Actions to run code scanning within GitHub. For information, see "Setting up code scanning for a repository."

The CodeQLランナー is a command-line tool that runs CodeQL analysis on a checkout of a GitHub repository. You add the runner to your third-party system, then call the runner to analyze code and upload the results to GitHub. These results are displayed as code scanning alerts in the repository.

Note:

  • The CodeQLランナー uses the CodeQL CLI to analyze code and therefore has the same license conditions. It's 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ランナー

You can download the CodeQLランナー 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

On Windows, the codeql-runner-win.exe file usually requires no change to permissions.

Adding the CodeQLランナー to your CI system

Once you download the CodeQLランナー and verify that it can be executed, you should make the runner available to each CI server that you intend to use for 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 GitHub, for example:

wget https://github.com/github/codeql-action/releases/latest/download/codeql-runner-linux
chmod +x codeql-runner-linux

In addition to this, each CI server also needs:

  • A GitHub App or personal access token for the CodeQLランナー to use. You must use an access token with the repo scope, or a GitHub App with the security_events write permission, and metadata and contents read permissions. For information, see "Building GitHub Apps" and "Creating a personal access token."
  • Access to the CodeQL bundle associated with this release of the CodeQLランナー. This package contains queries and libraries needed for CodeQL analysis, plus the CodeQL CLI, which is used internally by the runner. For information, see "CodeQL CLI."

The options for providing access to the CodeQL bundle are:

  1. Allow the CI servers access to https://github.com/github/codeql-action so that the CodeQLランナー 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 CodeQLランナー.

Calling the CodeQLランナー

You should call the CodeQLランナー 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 CodeQL database for each language to be analyzed. These databases are populated and analyzed by subsequent commands.
  2. analyze required to populate the CodeQL databases, analyze them, and upload results to GitHub.

For both commands, you must specify the URL of GitHub, 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.

You can configure where the CodeQLランナー 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 code scanning in your CI system."

ノート:

  • SARIF upload supports a maximum of 5000 results per upload. この制限を超えた結果は無視されます。 ツールがあまりに多くの結果を生成する場合、最も重要なルールやクエリに対する結果に焦点を当てるよう、設定を更新すべきです。

  • For each upload, SARIF upload supports a maximum size of 10 MB for the gzip-compressed SARIF file. Any uploads over this limit will be rejected. If your SARIF file is too large because it contains too many results, you should update the configuration to focus on results for the most important rules or queries.

Basic example

This example runs CodeQL analysis on a Linux CI server for the octo-org/example-repo repository hosted on https://github.com. The process is very simple because the repository contains only languages that can be analyzed by CodeQL directly, without being built (that is, Go, JavaScript, Python, and TypeScript).

In this example, the server has access to download the CodeQL bundle directly from the github/codeql-action repository, so there is no need to use the --codeql-path flag.

  1. Check out the repository to analyze.

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

  3. Initialize the CodeQLランナー and create CodeQL databases for the languages detected.

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo
        --github-url https://github.com --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.
  4. CodeQLデータベースを展開し、分析し、その結果をGitHubにアップロードしてください。 その結果は、リポジトリのSecurity(セキュリティ)タブに表示されます。

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.com --github-auth-stdin
        --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/my-branch
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results
  5. code scanningの結果をPull Requestのチェックとしてアップロードするには、 --ref フラグを使ってPull Requestを指定してください。 CodeQLランナーは、pull_request webhookイベントで実行されるようにセットアップすることをおすすめします。

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.com --github-auth-stdin
        --commit 1dc7a1346e5ce7b86835b68bbda3078b37d6abbe --ref refs/pull/123/merge
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results

code scanningアラートの表示に関する詳しい情報については「Code ScanningのアラートのPull Requestでのトリアージ」及び「<リポジトリの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 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 CodeQLランナー and create CodeQL databases for the languages detected.

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo-2
        --github-url https://github.com --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".
  4. Source the script generated by the init action 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
  5. Build the code. On macOS, you need to prefix the build command with the environment variable $CODEQL_RUNNER. For more information, see "Troubleshooting CodeQLランナー in your CI system."

  6. CodeQLデータベースを展開し、分析し、その結果をGitHubにアップロードしてください。 その結果は、リポジトリのSecurity(セキュリティ)タブに表示されます。

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.com --github-auth-stdin
        --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/my-branch
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results
  7. code scanningの結果をPull Requestのチェックとしてアップロードするには、 --ref フラグを使ってPull Requestを指定してください。 CodeQLランナーは、pull_request webhookイベントで実行されるようにセットアップすることをおすすめします。

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.com --github-auth-stdin
        --commit 1dc7a1346e5ce7b86835b68bbda3078b37d6abbe --ref refs/pull/123/merge
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results

code scanningアラートの表示に関する詳しい情報については「Code ScanningのアラートのPull Requestでのトリアージ」及び「<リポジトリのCode Scanningアラートの管理」を参照してください。

Note: If you use a containerized build, you need to run the CodeQLランナー in the container where your build task takes place.

Further reading

このドキュメントは役立ちましたか?

プライバシーポリシー

これらのドキュメントを素晴らしいものにするのを手伝ってください!

GitHubのすべてのドキュメントはオープンソースです。間違っていたり、はっきりしないところがありましたか?Pull Requestをお送りください。

コントリビューションを行う

OR, コントリビューションの方法を学んでください。

問題がまだ解決していませんか?