Configuring code scanning

Note: Your site administrator must enable 代� �扫描 for 您的 GitHub Enterprise Server 实例 before you can use this feature. If you want to use GitHub Actions to scan your code, the site administrator must also enable GitHub Actions and set up the infrastructure required. For more information, see "Configuring 代� �扫描 for your appliance."

Note: This article describes the features available with the version of the CodeQL action and associated CodeQL CLI bundle included in the initial release of this version of GitHub Enterprise Server. If your enterprise uses a more recent version of the CodeQL action, see the GitHub Enterprise Cloud article for information on the latest features. For information on using the latest version, see "Configuring code scanning for your appliance."

About 代� �扫描 configuration

You can run 代� �扫描 on GitHub Enterprise Server, using GitHub Actions, or from your continuous integration (CI) system. For more information, see "About GitHub Actions" or "About CodeQL 代� �扫描 in your CI system."

This article is about running 代� �扫描 on GitHub Enterprise Server using actions.

Before you can configure 代� �扫描 for a repository, you must set up 代� �扫描 by adding a GitHub Actions workflow to the repository. For more information, see "Setting up 代� �扫描 for a repository."

一般情况下� 需编辑代� �扫描的默认工作流程。但是，如果需要，您可以编辑工作流程以自定义某些设置。例如，您可以编辑 GitHub 的 CodeQL 分析工作流程来指定扫描频率、要扫描的语言或目录，以及 CodeQL 代� �扫描在代� �中的查找内容。如果您使用一组特定的命令来编译代� �，您可能还需要编辑 CodeQL 分析工作流程。

CodeQL analysis is just one type of 代� �扫描 you can do in GitHub. GitHub Marketplace on GitHub.com contains other 代� �扫描 workflows you can use. The specific examples given in this article relate to the CodeQL 分析工作流程 file.

Editing a 代� �扫描 workflow

GitHub saves workflow files in the .github/workflows directory of your repository. You can find a workflow you have added by searching for its file name. For example, by default, the workflow file for CodeQL 代� �扫描 is called codeql-analysis.yml.

In your repository, browse to the workflow file you want to edit.
In the upper right corner of the file view, to open the workflow editor, click .
After you have edited the file, click Start commit and complete the "Commit changes" form. You can choose to commit directly to the current branch, or create a new branch and start a pull request.

For more information about editing workflow files, see "Learn GitHub Actions."

Configuring frequency

You can configure the CodeQL 分析工作流程 to scan code on a schedule or when specific events occur in a repository.

Scanning code when someone pushes a change, and whenever a pull request is created, prevents developers from introducing new vulnerabilities and errors into the code. Scanning code on a schedule informs you about the latest vulnerabilities and errors that GitHub, security researchers, and the community discover, even when developers aren't actively maintaining the repository.

Scanning on push

By default, the CodeQL 分析工作流程 uses the on.push event to trigger a code scan on every push to the default branch of the repository and any protected branches. For 代� �扫描 to be triggered on a specified branch, the workflow must exist in that branch. For more information, see "Workflow syntax for GitHub Actions."

If you scan on push, then the results appear in the Security tab for your repository. For more information, see "Managing code scanning alerts for your repository."

Scanning pull requests

The default CodeQL 分析工作流程 uses the pull_request event to trigger a code scan on pull requests targeted against the default branch. The pull_request event is not triggered if the pull request was opened from a private fork.

For more information about the pull_request event, see "Events that trigger workflows."

If you scan pull requests, then the results appear as alerts in a pull request check. For more information, see "Triaging code scanning alerts in pull requests."

Avoiding unnecessary scans of pull requests

You might want to avoid a code scan being triggered on specific pull requests targeted against the default branch, irrespective of which files have been changed. You can configure this by specifying on:pull_request:paths-ignore or on:pull_request:paths in the 代� �扫描 workflow. For example, if the only changes in a pull request are to files with the file extensions .md or .txt you can use the following paths-ignore array.

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
    paths-ignore:
      - '**/*.md'
      - '**/*.txt'

Notes

on:pull_request:paths-ignore and on:pull_request:paths set conditions that determine whether the actions in the workflow will run on a pull request. They don't determine what files will be analyzed when the actions are run. When a pull request contains any files that are not matched by on:pull_request:paths-ignore or on:pull_request:paths, the workflow runs the actions and scans all of the files changed in the pull request, including those matched by on:pull_request:paths-ignore or on:pull_request:paths, unless the files have been excluded. For information on how to exclude files from analysis, see "Specifying directories to scan."
For CodeQL 代� �扫描 workflow files, don't use the paths-ignore or paths keywords with the on:push event as this is likely to cause missing analyses. For accurate results, CodeQL 代� �扫描 needs to be able to compare new changes with the analysis of the previous commit.

For more information about using on:pull_request:paths-ignore and on:pull_request:paths to determine when a workflow will run for a pull request, see "Workflow syntax for GitHub Actions."

Scanning on a schedule

If you use the default CodeQL 分析工作流程, the workflow will scan the code in your repository once a week, in addition to the scans triggered by events. To adjust this schedule, edit the cron value in the workflow. For more information, see "Workflow syntax for GitHub Actions."

Note: GitHub only runs scheduled jobs that are in workflows on the default branch. Changing the schedule in a workflow on any other branch has no effect until you merge the branch into the default branch.

Example

The following example shows a CodeQL 分析工作流程 for a particular repository that has a default branch called main and one protected branch called protected.

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '20 14 * * 1'

This workflow scans:

Every push to the default branch and the protected branch
Every pull request to the default branch
The default branch every Monday at 14:20 UTC

Specifying an operating system

If your code requires a specific operating system to compile, you can configure the operating system in your CodeQL 分析工作流程. Edit the value of jobs.analyze.runs-on to specify the operating system for the machine that runs your 代� �扫描 actions. You specify the operating system by using an appropriate label as the second element in a two-element array, after self-hosted.

jobs:
  analyze:
    name: Analyze
    runs-on: [self-hosted, ubuntu-latest]

CodeQL 代� �扫描 supports the latest versions of Ubuntu, Windows, and macOS. Typical values for this setting are therefore: ubuntu-latest, windows-latest, and macos-latest. For more information, see "Choosing the runner for a job" and "Using labels with self-hosted runners."

You must ensure that Git is in the PATH variable on your self-hosted runners. For more information, see "About self-hosted runners" and "Adding self-hosted runners."

For recommended specifications (RAM, CPU cores, and disk) for running CodeQL analysis, see "Recommended hardware resources for running CodeQL."

Changing the languages that are analyzed

CodeQL 代� �扫描 automatically detects code written in the supported languages.

C/C++
C#
Go
Java
JavaScript/TypeScript
Python

The default CodeQL 分析工作流程 file contains a matrix called language which lists the languages in your repository that are analyzed. CodeQL automatically populates this matrix when you add 代� �扫描 to a repository. Using the language matrix optimizes CodeQL to run each analysis in parallel. We recommend that all workflows adopt this configuration due to the performance benefits of parallelizing builds. For more information about matrices, see "Using a matrix for your jobs."

如果仓库中包含多种支持的语言的代� �，您可以选择要分析的语言。在有些情况下您可能需要阻止分析某种语言。例如，项目中可能存在与代� �主体语言不同的依赖项，并且您可能不希望看到关于这些依赖项的警报。

If your workflow uses the language matrix then CodeQL is hardcoded to analyze only the languages in the matrix. To change the languages you want to analyze, edit the value of the matrix variable. You can remove a language to prevent it being analyzed or you can add a language that was not present in the repository when 代� �扫描 was set up. For example, if the repository initially only contained JavaScript when 代� �扫描 was set up, and you later added Python code, you will need to add python to the matrix.

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        language: ['javascript', 'python']

If your workflow does not contain a matrix called language, then CodeQL is configured to run analysis sequentially. If you don't specify languages in the workflow, CodeQL automatically detects, and attempts to analyze, any supported languages in the repository. If you want to choose which languages to analyze, without using a matrix, you can use the languages parameter under the init action.

- uses: github/codeql-action/init@v1
  with:
    languages: cpp, csharp, python

Running additional queries

When you use CodeQL to scan code, the CodeQL analysis engine generates a database from the code and runs queries on it. CodeQL analysis uses a default set of queries, but you can specify more queries to run, in addition to the default queries.

Any additional queries you want to run must belong to a QL pack in a repository. For more information, see "About 代� �扫描 with CodeQL."

You can specify a single .ql file, a directory containing multiple .ql files, a .qls query suite definition file, or any combination. For more information about query suite definitions, see "Creating CodeQL query suites."

To add one or more queries, add a with: queries: entry within the uses: github/codeql-action/init@v1 section of the workflow. If the queries are in a private repository, use the external-repository-token parameter to specify a token that has access to checkout the private repository.

- uses: github/codeql-action/init@v1
  with:
    queries: COMMA-SEPARATED LIST OF PATHS
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

You can also specify query suites in the value of queries. Query suites are collections of queries, usually grouped by purpose or language.

以下查询套件内置于 CodeQL 代� �扫描，可供使用。

查询套件	描述
`security-extended`	严重性和精度低于默认查询的查询
`security-and-quality`	来自 `security-extended` 的查询，� 上可维护性和可� 性查询

When you specify a query suite, the CodeQL analysis engine will run the default set of queries and any extra queries defined in the additional query suite.

If you also use a configuration file for custom settings, any additional queries specified in your workflow are used instead of those specified in the configuration file. If you want to run the combined set of additional queries, prefix the value of queries in the workflow with the + symbol. For more information, see "Using a custom configuration file."

In the following example, the + symbol ensures that the specified additional queries are used together with any specified in the referenced configuration file.

- uses: github/codeql-action/init@v1
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main

Using a custom configuration file

A custom configuration file is an alternative way to specify additional queries to run. You can also use the file to disable the default queries and to specify which directories to scan during analysis.

In the workflow file, use the config-file parameter of the init action to specify the path to the configuration file you want to use. This example loads the configuration file ./.github/codeql/codeql-config.yml.

- uses: github/codeql-action/init@v1
  with:
    config-file: ./.github/codeql/codeql-config.yml

配置文件可以放在您分析的仓库内或外部仓库中。使用外部仓库允许您在一个位置指定多个仓库的配置选项。引用位于外部仓库中的配置文件时，您可以使用 OWNER/REPOSITORY/FILENAME@BRANCH 语法。例如 octo-org/shared/codeql-config.yml@main。

If the configuration file is located in an external private repository, use the external-repository-token parameter of the init action to specify a token that has access to the private repository.

- uses: github/codeql-action/init@v1
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

The settings in the configuration file are written in YAML format.

Specifying additional queries

You specify additional queries in a queries array. Each element of the array contains a uses parameter with a value that identifies a single query file, a directory containing query files, or a query suite definition file.

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

Optionally, you can give each array element a name, as shown in the example configuration files below. For more information about additional queries, see "Running additional queries" above.

Disabling the default queries

If you only want to run custom queries, you can disable the default security queries by using disable-default-queries: true.

Specifying directories to scan

For the interpreted languages that CodeQL supports (Python and JavaScript/TypeScript), you can restrict 代� �扫描 to files in specific directories by adding a paths array to the configuration file. You can exclude the files in specific directories from analysis by adding a paths-ignore array.

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

Note:

The paths and paths-ignore keywords, used in the context of the 代� �扫描 configuration file, should not be confused with the same keywords when used for on.<push|pull_request>.paths in a workflow. When they are used to modify on.<push|pull_request> in a workflow, they determine whether the actions will be run when someone modifies code in the specified directories. For more information, see "Workflow syntax for GitHub Actions."
The filter pattern characters ?, +, [, ], and ! are not supported and will be matched literally.
** characters can only be at the start or end of a line, or surrounded by slashes, and you can't mix ** and other characters. For example, foo/**, **/foo, and foo/**/bar are all allowed syntax, but **foo isn't. However you can use single stars along with other characters, as shown in the example. You'll need to quote anything that contains a * character.

For compiled languages, if you want to limit 代� �扫描 to specific directories in your project, you must specify appropriate build steps in the workflow. The commands you need to use to exclude a directory from the build will depend on your build system. For more information, see "Configuring the CodeQL workflow for compiled languages."

You can quickly analyze small portions of a monorepo when you modify code in specific directories. You'll need to both exclude directories in your build steps and use the paths-ignore and paths keywords for on.<push|pull_request> in your workflow.

Example configuration files

当您扫描代� �时，此配置文件将 security-and-quality 查询套件添� 到 CodeQL 运行的查询列表。有关可供使用的查询套件的更多信息，请参阅“运行其他查询”。

name: "My CodeQL config"

queries:
  - uses: security-and-quality

以下配置文件禁用默认查询，并指定一组要运行的自定义查询。它还配置 CodeQL 扫描 src 目录中的文件（相对于� �目录），并且排除 src/node_modules 目录以及名称以 .test.js 结尾的任何文件。 � 此，src/node_modules 中的文件以及名称以 .test.js 结尾的文件被排除在分析之外。

name: "My CodeQL config"

disable-default-queries: true

queries:
  - name: Use an in-repository QL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript QL pack (run queries from an external repo)
    uses: octo-org/javascript-qlpack@main
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths:
  - src 
paths-ignore: 
  - src/node_modules
  - '**/*.test.js'

Configuring 代� �扫描 for compiled languages

对于受支持的编译语言，您可以使用 CodeQL 分析工作流程中的 autobuild 操作来构建代� �。这� �您� 需为 C/C++、C# 和 Java 指定显式构建命令。 CodeQL 也运行 Go 项目的构建来设置项目。但是，与其他编译语言相比，仓库中的所有 Go 文件都是提取的，而不仅仅是构建的文件。您可以使用自定义构建命令跳过提取未受构建影响的 Go 文件。

如果仓库中的 C/C++、C# 或 Java 代� �含有非� �准的构建过程，autobuild 可能会失败。您需要从工作流程中� 除 autobuild 步骤，然后手动添� 构建步骤。如果您要指定仓库中的哪个 Go 文件要提取，则需要添� 生成步骤。 For more information about how to configure CodeQL 代� �扫描 for compiled languages, see "Configuring the CodeQL workflow for compiled languages."

Uploading 代� �扫描 data to GitHub

GitHub can display code analysis data generated externally by a third-party tool. You can upload code analysis data with the upload-sarif action. For more information, see "Uploading a SARIF file to GitHub."