此版本的 GitHub Enterprise 将停止服务 2022-02-16. 即使针对重大安全问题,也不会发布补丁。 要获得更好的性能、改进的安全性和新功能,请升级到 GitHub Enterprise 的最新版本。 如需升级方面的帮助,请联系 GitHub Enterprise 支持

Running CodeQL runner in your CI system

You can use the CodeQL runner to perform CodeQL 代码扫描 in a third-party continuous integration system.

代码扫描 在您拥有 GitHub Advanced Security 的许可证时可用。 更多信息请参阅“关于 GitHub Advanced Security”。

Note: The CodeQL runner 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 runner. On GitHub Enterprise Cloud, the CodeQL runner will be supported until March 2022. For more information, see the CodeQL runner deprecation.

注:站点管理员必须为 your GitHub Enterprise Server instance 启用 代码扫描,然后您才可使用此功能。 更多信息请参阅“为设备配置 代码扫描”。

About the CodeQL runner

The CodeQL runner is a tool you can use to run 代码扫描 on code that you're processing in a third-party continuous integration (CI) system. 代码扫描 是一项功能,可用于分析 GitHub 仓库中的代码,以查找安全漏洞和编码错误。 分析发现的任何问题都显示在 GitHub Enterprise Server 中。 For information, see "About 代码扫描 with CodeQL."

Alternatively, you can use GitHub Actions to run 代码扫描 within GitHub Enterprise Server. For information, see "Setting up 代码扫描 for a repository."

The CodeQL runner 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 Enterprise Server. These results are displayed as 代码扫描 alerts in the repository.

Note:

  • The CodeQL runner is available to customers with an Advanced Security license.

  • The CodeQL runner shouldn't be confused with the CodeQL CLI. The CodeQL CLI is a command-line interface that lets you create CodeQL databases for security research and run CodeQL queries. For more information, see "CodeQL CLI."

Downloading the CodeQL runner

You can download the CodeQL runner from https://HOSTNAME/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 runner to your CI system

Once you download the 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 代码扫描. 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://HOSTNAME/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 应用程序 or personal access token for the CodeQL runner to use. You must use an access token with the repo scope, or a GitHub 应用程序 with the security_events write permission, and metadata and contents read permissions. For information, see "Building GitHub 应用程序" and "Creating a personal access token."
  • Access to the CodeQL bundle associated with this release of the CodeQL runner. 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://HOSTNAME/github/codeql-action so that the 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 CodeQL runner.

Calling the CodeQL runner

You should call the 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 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 Enterprise Server.

For both commands, you must specify the URL of GitHub Enterprise Server, the repository OWNER/NAME, and the GitHub 应用程序 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 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 代码扫描 in your CI system."

注意:

  • SARIF upload supports a maximum of 1000 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.example.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 runner and create CodeQL databases for the languages detected.

    $ /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo
         --github-url https://github.example.com --github-auth TOKEN
  4. 填充 CodeQL 数据库、进行分析并将结果上传到 GitHub Enterprise Server。 结果将出现在仓库的 Security(安全性)选项卡中。

    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth TOKEN
        --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. 要将 代码扫描 结果上传为拉取请求检查,请使用 --ref 指定拉取请求 标志. 我们建议设置 CodeQL runner,以便它在发生 pull_request web 挂钩事件时运行。

    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth TOKEN
        --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

有关查看 代码扫描 警报的更多信息,请参阅“对拉取请求中的代码扫描警报分类”和“管理仓库的代码扫描警报”。

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 runner and create CodeQL databases for the languages detected.

    $ /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo-2
           --github-url https://github.example.com --github-auth TOKEN
  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 runner in your CI system."

  6. 填充 CodeQL 数据库、进行分析并将结果上传到 GitHub Enterprise Server。 结果将出现在仓库的 Security(安全性)选项卡中。

    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth TOKEN
        --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. 要将 代码扫描 结果上传为拉取请求检查,请使用 --ref 指定拉取请求 标志. 我们建议设置 CodeQL runner,以便它在发生 pull_request web 挂钩事件时运行。

    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth TOKEN
        --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

有关查看 代码扫描 警报的更多信息,请参阅“对拉取请求中的代码扫描警报分类”和“管理仓库的代码扫描警报”。

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

Further reading

此文档对您有帮助吗?

隐私政策

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或者, 了解如何参与。