代码扫描的工作流配置选项

先决条件

必须为 code scanning 使用高级设置，并能够编辑定义配置的工作流文件。

本文中提供的示例与 CodeQL 分析工作流程文件相关。默认情况下，该文件定义在 .github/workflows/codeql-analysis.yml。

扫描频率

可以将 CodeQL 分析工作流程配置为按计划或在存储库中发生特定事件时扫描代码。

每当推送到仓库以及每次创建拉取请求时，时扫描代码可防止开发者在代码中引入新的漏洞和错误。按时间表扫描可了解 GitHub、安全研究者和社区发现的最新漏洞和错误，即使开发者并未主动维护仓库。

按推送扫描

默认情况下，CodeQL 分析工作流程使用 on:push 事件在每次推送到存储库的默认分支和任何受保护分支时触发代码扫描。要使 code scanning 指定分支上触发，工作流程必须存在于该分支中。有关详细信息，请参阅“GitHub Actions 的工作流语法”。

如果在推送时扫描，结果会显示在存储库的安全性选项卡中。有关详细信息，请参阅“评估存储库的代码扫描警报”。

此外，当 on:push 扫描返回可映射到打开的拉取请求的结果时，这些警报将自动出现在拉取请求中，与其他拉取请求警报位于同一位置。警报是通过比较对分支头的现有分析与对目标分支的分析来确定的。有关拉取请求中 code scanning 警报的详细信息，请参阅鉴定拉取请求中的代码扫描警报。

扫描拉取请求

默认 CodeQL 分析工作流程使用 pull_request 事件在发生针对默认分支的拉取请求时触发代码扫描。如果拉取请求来自专用分支，则仅当你在存储库设置中选择了“从分支拉取请求运行工作流”选项时，才会触发 pull_request 事件。有关详细信息，请参阅“管理存储库的GitHub Actions设置”。

有关 pull_request 事件的详细信息，请参阅触发工作流的事件。

如果扫描拉取请求，结果将在拉取请求检查中显示为警报。有关详细信息，请参阅“鉴定拉取请求中的代码扫描警报”。

使用 pull_request 触发器（配置为扫描拉取请求的合并提交，而不是头提交）与每次推送时扫描分支头相比，可产生更高效且准确的结果。但是，如果使用的 CI/CD 系统无法配置为发生拉取请求时触发，你仍然可以使用 on:push 触发器和 code scanning 会将结果映射到在分支上打开的拉取请求，并将警报作为注释添加到拉取请求。有关详细信息，请参阅推送时扫描。

注意

如果存储库配置了合并队列，则需要将 merge_group 事件作为 code scanning 的附加触发器包含在内。这将确保在将拉取请求添加到合并队列时也会对其进行扫描。有关详细信息，请参阅“管理合并队列”。

避免对拉取请求进行不必要的扫描

你可能希望避免触发针对默认分支的特定拉取请求的代码扫描，而不考虑哪些文件已更改。可以通过在 code scanning 数据流中指定 on:pull_request:paths-ignore 或 on:pull_request:paths 来进行配置。例如，如果拉取请求中仅更改了文件扩展名为 .md 或 .txt 的文件，你可以使用以下 paths-ignore 数组。

YAML

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

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

注意

          `on:pull_request:paths-ignore` 和 `on:pull_request:paths` 可设置用于决定工作流中的操作是否将在发生拉取请求时运行的条件。 它们不会决定操作_运行_时将分析哪些文件。 当拉取请求包含任何未被 `on:pull_request:paths-ignore` 或 `on:pull_request:paths` 匹配的文件时，工作流会运行操作并扫描拉动请求中更改的所有文件，包括那些被 `on:pull_request:paths-ignore` 或 `on:pull_request:paths` 匹配的文件，除非这些文件已被排除。 有关如何从分析中排除文件的信息，请参阅[指定要扫描的目录](#specifying-directories-to-scan)。

有关使用 on:pull_request:paths-ignore 和 on:pull_request:paths 确定工作流何时为拉取请求运行的详细信息，请参阅 GitHub Actions 的工作流语法。

按时间表扫描

如果使用默认 CodeQL 分析工作流程，则除了由事件触发的扫描之外，工作流还将每周扫描一次存储库中的代码。要调整此计划，请在工作流中编辑 cron 事件对应的 on.schedule 值。有关详细信息，请参阅“GitHub Actions 的工作流语法”。

注意

仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。

示例

以下示例显示了特定存储库的 CodeQL 分析工作流程，该存储库具有一个名为 main 的默认分支和一个名为 protected 的受保护分支。

YAML

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

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

此工作流扫描：

对默认分支和受保护分支的每次推送
对默认分支的每个拉取请求
默认分支（每周一 14:20 UTC）

操作系统

注意

Swift 代码扫描默认使用 macOS 运行器。 GitHub 托管的 macOS 运行器比 Linux 和 Windows 运行器更昂贵，因此应考虑仅扫描生成步骤。有关如何为 Swift 配置代码扫描的详细信息，请参阅对编译语言进行 CodeQL 代码扫描。有关 GitHub 托管的运行器定价的详细信息，请参阅 GitHub Actions计费。
属于 Actions Runner Controller (ARC) 的运行器不支持 Swift 代码的 Code scanning，因为 ARC 运行器仅使用 Linux，且 Swift 需要 macOS 运行器。但是，你可以混合使用 ARC 运行器和自托管 macOS 运行器。有关详细信息，请参阅“Actions Runner Controller”。

如果代码需要特定的操作系统来编译，则可以在 CodeQL 分析工作流程中配置操作系统。编辑 jobs.analyze.runs-on 的值，指定运行 code scanning 操作的计算机操作系统。

YAML

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

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

如果选择使用自托管的运行程序进行代码扫描，可以在 self-hosted 之后使用适当的标签作为二元素数组中的第二个元素来指定操作系统。

YAML

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

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

CodeQL code scanning 支持最新版本的 Ubuntu、Windows 和 macOS。因此，此设置的典型值为：ubuntu-latest、windows-latest 和 macos-latest。有关详细信息，请参阅选择作业的运行器和将标签与自托管运行程序结合使用。

如果使用自托管运行器，必须确保 Git 位于 PATH 变量中。有关详细信息，请参阅自托管运行程序和添加自托管的运行器。

有关在自托管计算机上运行 CodeQL 分析的建议规范（RAM、CPU 核心和磁盘），请参阅推荐用于运行 CodeQL 的硬件资源。

CodeQL 数据库位置

通常，无需担心 CodeQL 分析工作流程将 CodeQL 数据库放置的位置，因为后面的步骤会自动查找前面步骤创建的数据库。但是，如果你正在编写一个自定义工作流步骤，要求 CodeQL 数据库位于特定的磁盘位置，例如将数据库作为工作流工件上传，则可以使用 db-location 下的 init 参数指定该位置。

YAML

- uses: github/codeql-action/init@v4
  with:
    db-location: '${{ github.runner_temp }}/my_location'

- uses: github/codeql-action/init@v4
  with:
    db-location: '${{ github.runner_temp }}/my_location'

CodeQL 分析工作流程期望 db-location 中提供的路径是可写的，或者不存在，或者是一个空目录。当在运行自托管运行器或使用 Docker 容器的作业中使用此参数时，用户有责任确保所选目录在运行之间被清空，或数据库一旦不再需要即予移除。对于在 GitHub 托管的运行器中运行的作业来说，这不是必需的，因为每次运行时都会获得一个新的实例和一个干净的文件系统。有关详细信息，请参阅“GitHub 托管的运行程序”。

如果不使用此参数，CodeQL 分析工作流程将在自己选择的临时位置创建数据库。当前默认值为 ${{ github.runner_temp }}/codeql_databases。

要分析的语言

CodeQL code scanning 支持使用以下语言编写的代码：

C/C++
C#
Go
Java/Kotlin
JavaScript/TypeScript
Python
Ruby
Rust
切换 * GitHub Actions工作流

注意

使用 java-kotlin 分析用 Java 或/和 Kotlin 编写的代码。
使用 javascript-typescript 分析用 JavaScript 和/或 TypeScript 编写的代码。

有关详细信息，请参阅 CodeQL 网站上的文档：“支持的语言和框架”。

CodeQL 使用以下语言标识符：

语言	Identifier	可选替代标识符（如果有）
C/C++	`c-cpp`

          `c` 或 `cpp` |

注意

如果指定替代标识符之一，则等效于使用标准语言标识符。例如，指定 javascript 而不是 javascript-typescript 不排除对 TypeScript 代码的分析。相反，可以使用自定义配置文件来使用 paths-ignore 设置从分析中排除文件。有关详细信息，请参阅使用自定义配置文件和指定要扫描的目录。

这些语言标识符可用作 languages 操作的 init 输入的参数。建议仅提供一种语言作为参数：

YAML

- uses: github/codeql-action/init@v4
  with:
    languages: javascript-typescript

- uses: github/codeql-action/init@v4
  with:
    languages: javascript-typescript

          [使用 CodeQL 配置用于代码扫描的高级设置](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning#configuring-advanced-setup-for-code-scanning-with-codeql)后创建的默认 CodeQL 分析工作流程 文件将定义一个矩阵，其中包含名为 `language` 的属性，该属性将列出要分析的存储库中的语言。 此矩阵已自动预填充在存储库中检测到的受支持语言。 使用 `language` 矩阵允许 CodeQL 并行运行每种语言分析并自定义每种语言的分析。 在单个分析中，矩阵中语言的名称将作为 `init` 输入的参数提供给 `languages` 操作。 建议所有工作流都采用此配置。 有关矩阵的详细信息，请参阅“[AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs)”。

YAML

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}

如果工作流使用 language 矩阵，则 CodeQL 将只会分析该矩阵中的语言。若要更改要分析的语言，请编辑矩阵配置。可以删除语言以避免对其进行分析。有几种原因可能使你想阻止对某种语言进行分析。例如，项目中可能有其他语言的代码主体依赖项，你可能不想看到这些依赖项的警报。还可在配置 code scanning 时添加存储库中不存在的语言。例如，如果在配置 code scanning 时存储库最初只包含 JavaScript，而后来添加了 Python 代码，则需要向矩阵中添加 python。

YAML

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

对于已编译的语言，矩阵还可用于通过更改 build-mode 属性的值来配置应用于分析的生成模式。有关生成模式的详细信息，请参阅“对编译语言进行 CodeQL 代码扫描”。

如果工作流未向 languages 操作的 init 输入提供参数，则 CodeQL 将配置为按顺序运行分析。在这种情况下，CodeQL 会自动检测和尝试分析存储库中的任何受支持语言。根据存储库的大小和语言数量，这可能需要很长时间。如果一种语言的分析在此模式下失败，则所有语言的分析都将失败。因此不建议使用此配置。

注意

按顺序分析语言时，系统将默认使用每种语言的默认生成模式。另一种情况是，如果你提供了显式的 autobuild 步骤，则所有支持 autobuild 模式的语言都将使用该模式，而其他语言则使用其默认模式。如果需要比这更复杂的生成模式配置，则需要配置矩阵。

检测失败警报的严重性

当满足以下条件之一时，可以使用规则集防止合并拉取请求：

某个必需的工具发现了一个 code scanning 警报，且该警报的严重程度符合规则集中的定义。
所需的工具分析仍在进行中。
未为存储库配置所需的工具。

有关详细信息，请参阅“设置代码扫描合并保护”。有关规则集的更多常规信息，请参阅“关于规则集”。

分析类别

使用 category 区分针对同一工具和提交的多个分析，但在不同的语言或代码的不同部分执行。你在工作流程中指定的类别将包含在 SARIF 结果文件中。

如果你使用单一仓库，并且对单一仓库的不同部分有多个对应的 SARIF 文件，此参数是特别有用。

YAML

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v4
      with:
        # Optional. Specify a category to distinguish between multiple analyses
        # for the same tool and ref. If you don't use `category` in your workflow,
        # GitHub will generate a default category name for you
        category: "my_category"

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v4
      with:
        # Optional. Specify a category to distinguish between multiple analyses
        # for the same tool and ref. If you don't use `category` in your workflow,
        # GitHub will generate a default category name for you
        category: "my_category"

如果未在工作流中指定 category 参数，则 GitHub 将基于触发操作的工作流文件的名称、操作名称和任何矩阵变量生成类别名称。例如： * .github/workflows/codeql-analysis.yml 工作流和 analyze 操作将生成类别 .github/workflows/codeql.yml:analyze。 * .github/workflows/codeql-analysis.yml 工作流、analyze 操作和 {language: javascript-typescript, os: linux} 矩阵变量将生成类别 .github/workflows/codeql-analysis.yml:analyze/language:javascript-typescript/os:linux。

          `category` 值将显示为 `<run>.automationDetails.id` SARIF v2.1.0 中的属性。 有关详细信息，请参阅“[AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#runautomationdetails-object)”。

指定的类别不会覆盖 SARIF 文件中 runAutomationDetails 对象的详细信息（如果已包含）。

CodeQL 模型包

如果代码库依赖于 CodeQL 中的标准查询无法识别的库或框架，则可以通过指定已发布的 CodeQL 模型包来扩展 code scanning 工作流中的 CodeQL 覆盖范围。有关创建自己的模型包的详细信息，请参阅创建并使用 CodeQL 包。

注意

CodeQL 模型包目前包含在公共预览版中，可能会更改。 C/C++、C#、Java/Kotlin、Python、Ruby 和 Rust 分析支持模型包。

Visual Studio Code 的 CodeQL 扩展中的 CodeQL 支持对 C#、Java/Kotlin、Python 和 Ruby 的依赖项建模。

使用 CodeQL 模型包

要添加一个或多个已发布的 CodeQL 模型包，请在工作流 with: packs: 部分的 uses: github/codeql-action/init@v4 条目中指定这些模型包。在 packs 中，可以指定要使用的一个或多个包，还可以指定要下载的版本。在未指定版本的情况下，将下载最新版本。如果要使用不可公开使用的包，则需要将 GITHUB_TOKEN 环境变量设置为有权访问包的机密。有关详细信息，请参阅在工作流中使用 GITHUB_TOKEN 进行身份验证和在 GitHub Actions 中使用机密。

YAML

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: security-extended
    packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: security-extended
    packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack

在此示例中，将针对Java运行默认查询，以及对于查询包7.8.9中版本号大于或等于7.9.0且小于my-company/my-java-queries的查询进行运行。在最新版本的模型包 my-repo/my-java-model-pack 中建模的依赖项可用于默认查询和 my-company/my-java-queries 中的查询。

非默认查询

使用 CodeQL 扫描代码时，CodeQL 分析引擎将从代码生成数据库并对其运行查询。 CodeQL 分析使用默认的查询集，但除了默认查询外，您还可以指定更多的查询来运行。

提示

还可以指定要从分析中排除或是包含在分析中的查询。这需要使用自定义配置文件。有关详细信息，请参阅自定义配置文件和从下面的分析中排除特定查询。

如果它们是发布到 GitHub Container registry 的 CodeQL 包或存储在存储库中的 CodeQL 包的一部分，则可以运行额外的查询。有关详细信息，请参阅“关于使用 CodeQL 进行代码扫描”。

可用于指定要运行的其他查询的选项有：

          `packs`，可安装一个或多个 CodeQL 查询包并为这些包运行默认查询套件或查询。

        `queries`，可指定单个 .ql 文件、包含多个 .ql 文件的目录、.qls 查询套件定义文件或任意组合  。 有关查询套件定义的详细信息，请参阅“[创建 CodeQL 查询套件](https://codeql.github.com/docs/codeql-cli/creating-codeql-query-suites/)”。

可以在同一工作流中同时使用 packs 和 queries。

不建议直接从 github/codeql 存储库引用查询套件，例如 github/codeql/cpp/ql/src@main。此类查询必须重新编译，并且可能与 GitHub Actions 上当前活动的 CodeQL 版本不兼容，这可能会导致分析过程中出错。

使用查询包

若要添加一个或多个 CodeQL 查询包，请在工作流的 with: packs: 部分中添加一个 uses: github/codeql-action/init@v4 条目。在 packs 中，可以指定要使用的一个或多个包，还可以指定要下载的版本。在未指定版本的情况下，将下载最新版本。如果要使用不可公开使用的包，则需要将 GITHUB_TOKEN 环境变量设置为有权访问包的机密。有关详细信息，请参阅在工作流中使用 GITHUB_TOKEN 进行身份验证和在 GitHub Actions 中使用机密。

注意

对于为多种语言生成 CodeQL 数据库的工作流，你必须改为在配置文件中指定 CodeQL 查询包。有关详细信息，请参阅下面的指定 CodeQL 查询包。

在下面的示例中，scope 是发布包的组织或个人帐户。工作流运行时，将从 GitHub 下载四个 CodeQL 查询包，并运行每个包的默认查询或查询套件：

下载最新版本的 pack1 并运行所有默认查询。
下载版本 1.2.3 的 pack2 并运行所有默认查询。
下载与版本 3.2.1 兼容的最新版本 pack3，并运行所有查询。
下载 4.5.6 版本的 pack4，并且仅运行在 path/to/queries 中找到的查询。

YAML

- uses: github/codeql-action/init@v4
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/[email protected],scope/pack3@~3.2.1,scope/[email protected]:path/to/queries

- uses: github/codeql-action/init@v4
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/[email protected],scope/pack3@~3.2.1,scope/[email protected]:path/to/queries

注意

如果指定要使用的查询包的特定版本，需注意你指定的版本最终可能太旧，使得无法由 CodeQL 操作使用的默认 CodeQL 引擎有效使用。为了确保最佳性能，如果需要指定确切的查询包版本，应考虑定期查看是否需要前移所固定的查询包版本。

有关包兼容性的详细信息，请参阅 CodeQL 查询包参考。

从 GitHub Enterprise Server 下载 CodeQL 包

如果工作流使用在 GitHub Enterprise Server 安装上发布的包，则需要告知工作流在何处查找这些包。为此，可以使用 github/codeql-action/init@v4 操作的 registries 输入。此输入接受 url、packages 和 token 属性的列表，如下所示。

YAML

- uses: github/codeql-action/init@v4
  with:
    registries: |
      # URL to the container registry, usually in this format
      - url: https://containers.GHEHOSTNAME1/v2/

        # List of package glob patterns to be found at this registry
        packages:
          - my-company/*
          - my-company2/*

        # Token, which should be stored as a secret
        token: ${{ secrets.GHEHOSTNAME1_TOKEN }}

      # URL to the default container registry
      - url: https://ghcr.io/v2/
        # Packages can also be a string
        packages: "*/*"
        token: ${{ secrets.GHCR_TOKEN }}

- uses: github/codeql-action/init@v4
  with:
    registries: |
      # URL to the container registry, usually in this format
      - url: https://containers.GHEHOSTNAME1/v2/

        # List of package glob patterns to be found at this registry
        packages:
          - my-company/*
          - my-company2/*

        # Token, which should be stored as a secret
        token: ${{ secrets.GHEHOSTNAME1_TOKEN }}

      # URL to the default container registry
      - url: https://ghcr.io/v2/
        # Packages can also be a string
        packages: "*/*"
        token: ${{ secrets.GHCR_TOKEN }}

注册表列表中的包模式按顺序进行检查，因此通常应将最具体的包模式放在最前面。 token 的值必须是通过 read:packages 权限从中下载的 GitHub 实例生成的 personal access token (classic)。

注意 | 属性名称之后的 registries。这一点很重要，因为 GitHub Actions 输入只能接受字符串。使用 | 将后续文本转换为字符串，稍后由 github/codeql-action/init@v4 操作分析。

在 QL 包中使用查询

若要添加一个或多个查询，请在工作流的 with: queries: 部分中添加一个 uses: github/codeql-action/init@v4 条目。如果查询在专用存储库中，请使用 external-repository-token 参数来指定具有签出专用存储库访问权限的令牌。

还可以在 queries 的值中指定查询套件。查询套件是查询的集合，通常按用途或语言进行分组。

YAML

- uses: github/codeql-action/init@v4
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

- uses: github/codeql-action/init@v4
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

以下查询套件内置于 CodeQL code scanning，可供使用。

查询套件	描述
`security-extended`	来自默认套件的查询，以及较低严重性和精度查询
`security-and-quality`	来自 `security-extended` 的查询，以及可维护性和可靠性查询。

有关详细信息，请参阅“CodeQL 查询套件”。

其中每个查询套件都包含该语言的内置 CodeQL 查询包中随附的不同查询子集。查询套件是使用每个查询的元数据自动生成的。有关详细信息，请参阅“CodeQL 查询的元数据”。

指定查询套件时，CodeQL 分析引擎将运行默认查询集和其他查询套件中定义的任何其他查询。

使用自定义配置文件

如果还使用配置文件进行自定义设置，则将使用工作流中指定的任意其他包或查询，而不是配置文件中指定的包或查询。如何要运行一组额外的包或查询的组合，请在工作流中的 packs 或 queries 的值前面加上 + 符号。有关详细信息，请参阅自定义配置文件。

在下面的示例中，+ 符号确保指定的附加包和查询与引用的配置文件中指定的任何包和查询一起使用。

YAML

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/[email protected],scope/[email protected]:path/to/queries

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/[email protected],scope/[email protected]:path/to/queries

自定义配置文件

自定义配置文件是指定要运行的其他包和查询的替代方法。还可以使用该文件禁用默认查询，排除或包含特定查询，并指定在分析期间要扫描的目录。

在工作流文件中，使用 config-file 操作的 init 参数指定要使用的配置文件的路径。此示例加载配置文件 ./.github/codeql/codeql-config.yml。

YAML

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

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

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

如果配置文件位于外部专用存储库中，请使用 external-repository-token 操作的 init 参数指定有权访问专用存储库的令牌。

YAML

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

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

配置文件中的设置以 YAML 格式编写。

指定 CodeQL 查询包

在数组中指定 CodeQL 查询包。请注意，格式与工作流文件使用的格式不同。

YAML

packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/[email protected]
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/[email protected]
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

指定查询包的完整格式为 scope/name[@version][:path]。 version和path都是可选的。 version 是 semver 版本范围。如果缺少该版本，则使用最新版本。有关 semver 范围的详细信息，请参阅 npm 上的 semver 文档。

如果你的工作流程生成多个 CodeQL 数据库，则可以使用包的嵌套映射指定要在自定义配置文件中运行的任何 CodeQL 查询包。

YAML

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/[email protected]

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/[email protected]

利用威胁模型扩展 CodeQL 覆盖率

注意

风险模型功能目前为公共预览版，可能随时更改。在公共预览版期间，风险模型仅支持 Java/Kotlin 和 C# 分析。

默认威胁模型包括不受信任的数据的远程源。可以在自定义配置文件中指定 threat-models: local 以扩展 CodeQL 威胁模型，从而包含不受信任的数据的本地源（例如命令行参数、环境变量、文件系统和数据库）。如果扩展威胁模型，还将使用默认的威胁模型。

指定额外查询

在 queries 数组中指定其他查询。数组的每个元素都包含一个 uses 参数，其值标识单个查询文件、包含查询文件的目录或查询套件定义文件。

YAML

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

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

（可选）你可以给每个数组元素一个名称，如下面的示例配置文件所示。有关其他查询的详细信息，请参阅上面的非默认查询。

禁用默认查询

如果只想运行自定义查询，可以使用 disable-default-queries: true 禁用默认安全查询。

从分析中排除特定查询

可以向自定义配置文件添加 exclude 和 include 筛选器，以指定要在分析中排除或包含的查询。

这在要排除诸如以下内容时非常有用：

来自默认套件的特定查询（security、security-extended 和security-and-quality）。
对其结果不感兴趣的特定查询。
生成警告和建议的所有查询。

可以使用 exclude 筛选器（类似于以下配置文件中的筛选器）来排除要从默认分析中移除的查询。在以下配置文件示例中，js/redundant-assignment 和 js/useless-assignment-to-local 查询都从分析中排除。

YAML

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

若要查找查询的 ID，可以在安全性选项卡中的警报列表中单击警报。此操作会打开警报详细信息页。 Rule ID 字段包含查询 ID。有关警报详细信息页的详细信息，请参阅关于代码扫描警报。

提示

筛选器的顺序非常重要。在有关查询和查询包的指令之后出现的第一个筛选器指令确定在默认情况下是包含还是排除查询。
后续指令按顺序执行，在文件后面出现的指令优先于前面的指令。

可以在示例配置文件部分中找到说明这些筛选器的使用的另一个示例。

有关在自定义配置文件中使用 exclude 和 include 筛选器的详细信息，请参阅创建 CodeQL 查询套件。有关可以筛选的查询元数据的信息，请参阅 CodeQL 查询的元数据。

指定要扫描的目录

在不生成代码的情况下分析代码库时，可以通过将 paths 数组添加到配置文件，从而将code scanning限定为特定目录中的文件。还可以通过添加 paths-ignore 数组来从分析中排除特定目录中的文件。当您在解释型语言（Python、Ruby 和 JavaScript/TypeScript）上运行数据变量.product.prodname_codeql %} 操作时，或者在不生成代码的情况下分析编译型语言（当前支持数据变量.code-scanning.no_build_support %}）时，可以使用此选项。

YAML

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

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

注意

在 code scanning 配置文件的上下文中使用的 paths 和 paths-ignore 关键字在工作流中用于 on.<push|pull_request>.paths 时不应与相同的关键字混淆。当它们用于修改工作流中的 on.<push|pull_request> 时，它们确定当有人修改指定目录中的代码时是否会运行这些操作。有关详细信息，请参阅“GitHub Actions 的工作流语法”。
筛选模式字符 ?、+、[、] 和 ! 不受支持，将按字面意思进行匹配。

          `**` 字符只能位于行首或行尾，或被斜线包围，并且不能混用 `**` 和其他字符。 例如，`foo/**`、`**/foo` 和 `foo/**/bar` 都是允许的语法，但 `**foo` 不是。 但是，可以将单星与其他字符一起使用，如示例中所示。 需要引用包含 `*` 字符的任何内容。

对于生成代码的分析，如果要将code scanning限定为项目中的特定目录，则必须在工作流中指定适当的生成步骤。需要用于从构建中排除目录的命令取决于你的构建系统。有关详细信息，请参阅“对编译语言进行 CodeQL 代码扫描”。

修改特定目录中的代码时，可以快速分析单存储库的一小部分。需要在构建步骤中排除目录，并在工作流中为 paths-ignore 使用 paths 和 on.<push|pull_request> 关键字。

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}
    config: |
      disable-default-queries: true
      threat-models: local
      queries:
        - uses: security-extended
      query-filters:
        - exclude:
            tags: /cwe-020/

可以使用同一方法在工作流文件中指定任何有效的配置选项。

提示

可以使用 GitHub Actions 变量跨多个存储库共享一个配置。此方法的一个好处是，无需编辑工作流文件即可在单个位置更新配置。

在以下示例中，vars.CODEQL_CONF 是 GitHub Actions 变量。其值可以是任何有效配置文件的内容。有关详细信息，请参阅“在变量中存储信息”。

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}
    config: ${{ vars.CODEQL_CONF }}

已编译的语言

对于已编译语言，可以决定 CodeQL 操作如何创建用于分析的 CodeQL 数据库。有关可用生成选项的信息，请参阅“对编译语言进行 CodeQL 代码扫描”。

数据上传

GitHub 可显示通过第三方工具在外部生成的代码分析数据。可以使用 upload-sarif 操作上传代码分析数据。有关详细信息，请参阅“将 SARIF 文件上传到 GitHub”。

代码扫描的工作流配置选项

谁可以使用此功能？

在本文中

先决条件

扫描频率

按推送扫描

扫描拉取请求

避免对拉取请求进行不必要的扫描

按时间表扫描

示例

操作系统

CodeQL 数据库位置

要分析的语言

检测失败警报的严重性

分析类别

CodeQL 模型包

使用 CodeQL 模型包

非默认查询

使用查询包

从 GitHub Enterprise Server 下载 CodeQL 包

在 QL 包中使用查询

使用自定义配置文件

自定义配置文件

指定 CodeQL 查询包

利用威胁模型扩展 CodeQL 覆盖率

指定额外查询

禁用默认查询

从分析中排除特定查询

指定要扫描的目录

示例配置文件

配置详细信息

配置示例

已编译的语言

数据上传