自定义代码扫描的高级设置

Note

网站管理员必须启用 code scanning，然后你才能使用此功能。如果要使用 GitHub Actions 扫描代码，站点管理员还必须启用 GitHub Actions 并设置所需的基础结构。有关详细信息，请参阅“为设备配置代码扫描”。

Note

本文介绍了此版 GitHub Enterprise Server 的初始发行版中包含的 CodeQL 操作版本和相关 CodeQL CLI 捆绑包中可用的功能。如果企业使用较新版本的 CodeQL 操作，请参阅本文的 GitHub Enterprise Cloud 版本，了解有关最新功能的信息。有关使用最新版本的信息，请参阅“为设备配置代码扫描”。

关于 code scanning 配置

你可以使用 GitHub Actions 在 GitHub Enterprise Server 中运行 code scanning，或从持续集成 (CI) 系统运行它。有关详细信息，请参阅“写入工作流”或“在现有 CI 系统上使用代码扫描”。

通过 code scanning 的高级设置，你可以自定义 code scanning 工作流，以便更精细地控制你的配置。有关详细信息，请参阅“配置代码扫描的高级设置”。

CodeQL 分析只是你可以在 GitHub 中执行的一种 code scanning。 GitHub Marketplace 在 GitHub.com 上，包含你可以使用的其他 code scanning 工作流程。本文中提供的特定示例与 CodeQL 分析工作流程文件相关****。

编辑 code scanning 工作流

GitHub 将工作流文件保存在存储库的 .github/workflows 目录中。可搜索文件名来查找已添加的工作流。例如，默认情况下，CodeQL code scanning 的工作流文件称为 codeql-analysis.yml。

在仓库中，浏览至要编辑的工作流程文件。
若要打开工作流编辑器，请在文件视图右上角单击。
编辑完文件后，请单击“开始提交”，并完成“提交更改”窗体。可以选择直接提交到当前分支，也可以创建一个新分支，并发起拉取请求。

有关编辑工作流文件的详细信息，请参阅“写入工作流”。

配置频率

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

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

按推送扫描

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

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

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

扫描拉取请求

默认 CodeQL 分析工作流程使用 pull_request 事件在发生针对默认分支的拉取请求时触发代码扫描。如果从专用分支打开拉取请求，则不会触发 pull_request 事件。

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

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

使用 pull_request 触发器（配置为扫描拉取请求的合并提交，而不是头提交）与每次推送时扫描分支头相比，可产生更高效且准确的结果。但是，如果使用的 CI/CD 系统无法配置为发生拉取请求时触发，你仍然可以使用 on:push 触发器和 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'

Note

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 匹配的文件，除非这些文件已被排除。有关如何从分析中排除文件的信息，请参阅“指定要扫描的目录”。

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

按时间表扫描

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

Note

GitHub 仅运行默认分支上的工作流中的计划作业。在任何其他分支上的工作流程中更改时间表后，需要将该分支合并到默认分支才能使更改生效。

示例

以下示例显示了特定存储库的 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）

指定操作系统

Note

Swift 代码扫描默认使用 macOS 运行器。
属于 Actions Runner Controller (ARC) 的运行器不支持 Swift 代码的 Code scanning，因为 ARC 运行器仅使用 Linux，且 Swift 需要 macOS 运行器。但是，你可以混合使用 ARC 运行器和自托管 macOS 运行器。有关详细信息，请参阅“关于 Actions Runner Controller”。

如果代码需要特定的操作系统来编译，则可以在 CodeQL 分析工作流程中配置操作系统。编辑 jobs.analyze.runs-on 的值，指定运行 code scanning 操作的计算机操作系统。通过在 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 分析，请参阅“推荐用于运行 CodeQL 的硬件资源”。

指定 CodeQL 数据库的位置

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

YAML

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

- uses: github/codeql-action/init@v3
  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
Swift

Note

使用 java-kotlin 分析用 Java、Kotlin 或两者共同编写的代码。
使用 javascript-typescript 分析用 JavaScript、TypeScript 或两者共同编写的代码。

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

CodeQL 使用以下语言标识符：

语言	Identifier	可选替代标识符（如果有）
C/C++	`c-cpp`	`c` 或 `cpp`
C#	`csharp`
Go	`go`
Java/Kotlin	`java-kotlin`	`java` 或 `kotlin`
JavaScript/TypeScript	`javascript-typescript`	`javascript` 或 `typescript`
Python	`python`
Ruby	`ruby`
Swift	`swift`

Note

如果指定替代标识符之一，则等效于使用标准语言标识符。例如，指定 javascript 而不是 javascript-typescript 不排除对 TypeScript 代码的分析。可以使用 --paths-ignore 选项在高级设置工作流中执行此操作。有关详细信息，请参阅“自定义代码扫描的高级设置”。

默认 CodeQL 分析工作流程文件包含一个名为 language 的矩阵，其中列出了存储库中要分析的语言。将 code scanning 添加到仓库时，CodeQL 会自动填充此矩阵。使用 language 矩阵优化 CodeQL 以并行运行每个分析。由于并行生成的性能优势，建议所有工作流都采用此配置。有关矩阵的详细信息，请参阅“在工作流中运行作业的变体”。

如果存储库包含的代码支持多种语言，可以选择要分析的语言。有几种原因可能使你想阻止对某种语言进行分析。例如，项目中可能有其他语言的代码主体依赖项，你可能不想看到这些依赖项的警报。

如果工作流使用 language 矩阵，则 CodeQL 会被硬编码为仅分析矩阵中的语言。若要更改要分析的语言，请编辑 matrix 变量的值。可以删除某种语言以防止被分析，也可以添加在配置 code scanning 时存储库中不存在的语言。例如，如果在配置 code scanning 时存储库最初只包含 JavaScript，而后来添加了 Python 代码，则需要向矩阵中添加 python。

YAML

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

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

如果工作流程中不包含名为 language 的矩阵，则 CodeQL 将被配置为按顺序运行分析。如果你未在工作流程中指定语言，则 CodeQL 将自动检测并尝试分析仓库中所有受支持的语言。如果要选择要分析的语言，而不使用矩阵，则可以在 init 操作下使用 languages 参数。

YAML

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

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

定义导致拉取请求检查失败的警报严重性

在拉取请求上启用 code scanning 时，仅当检测到一个或多个严重性为 error 或者安全严重性为 critical 或 high 的警报时，检查才会失败。如果检测到严重性或安全严重性低于此标准的警报，则检查将会成功。对于重要的代码库，则建议设置为 code scanning 检查在检测到任何警报时失败，以确保在合并代码更改之前必须修正或消除警报。有关严重性级别的详细信息，请参阅“关于警报严重性和安全严重性级别”。

可以编辑导致检查失败的严重性和安全严重性警报级别。有关详细信息，请参阅“编辑默认设置配置”。

配置分析类别

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

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

YAML

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v3
      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@v3
      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 Enterprise Server 将基于触发操作、操作名称和任何矩阵变量的工作流文件的名称生成类别名称。例如：

.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 中的属性。有关详细信息，请参阅“对代码扫描的 SARIF 支持”。

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

在使用 CodeQL 模型包扩展 CodeQL 覆盖范围

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

Note

CodeQL 模型包和 CodeQL 模型编辑器当前为 beta 版本，可能随时更改。模型包由 Java/Kotlin 分析支持。

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

YAML

- uses: github/codeql-action/init@v3
  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@v3
  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 分析使用默认的查询集，但除了默认查询外，您还可以指定更多的查询来运行。

Tip

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

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

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

packs，可安装一个或多个 CodeQL 查询包并为这些包运行默认查询套件或查询。
queries，可指定单个 .ql 文件、包含多个 .ql 文件的目录、.qls 查询套件定义文件或任意组合。有关查询套件定义的详细信息，请参阅“创建 CodeQL 查询套件”。

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

使用查询包

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

Note

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

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

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

YAML

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

Note

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

有关包兼容性的详细信息，请参阅“发布及使用 CodeQL 包”。

从 GitHub Enterprise Server 下载 CodeQL 包

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

YAML

- uses: github/codeql-action/init@v3
  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@v3
  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@v3 操作分析。

在 QL 包中使用查询

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

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

YAML

- uses: github/codeql-action/init@v3
  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@v3
  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@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries

使用自定义配置文件

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

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

YAML

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

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

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

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

YAML

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

- uses: github/codeql-action/init@v3
  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/pack2@1.2.3
  # 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/pack2@1.2.3
  # 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/java-pack2@v1.0.0

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/java-pack2@v1.0.0

指定额外查询

在 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。有关警报详细信息页的详细信息，请参阅“关于代码扫描警报”。

Tip

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

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

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

指定要扫描的目录

在不生成代码的情况下分析代码库时，可以通过将 paths 数组添加到配置文件，从而将code scanning限定为特定目录中的文件。还可以通过添加 paths-ignore 数组来从分析中排除特定目录中的文件。在解释语言（Python、Ruby 和JavaScript/TypeScript）上运行 CodeQL 操作时可以使用此选项。

YAML

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

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

Note

在 code scanning 配置文件的上下文中使用的 paths 和 paths-ignore 关键字在工作流中用于 on.<push|pull_request>.paths 时不应与相同的关键字混淆。当它们用于修改工作流中的 on.<push|pull_request> 时，它们确定当有人修改指定目录中的代码时是否会运行这些操作。有关详细信息，请参阅“GitHub Actions 的工作流语法”。
筛选模式字符 ?、+、[、] 和 ! 不受支持，将按字面意思进行匹配。
** 字符只能位于行首或行尾，或被斜线包围，并且不能混用 ** 和其他字符。例如，foo/**、**/foo 和 foo/**/bar 都是允许的语法，但 **foo 不是。但是，可以将单星与其他字符一起使用，如示例中所示。需要引用包含 * 字符的任何内容。

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

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

示例配置文件

当扫描代码时，此配置文件将 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 CodeQL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript CodeQL pack (run queries from an external repo)
    uses: octo-org/javascript-codeql-pack@main
  - name: Use an external query (run a single query from an external CodeQL pack)
    uses: octo-org/python-codeql-pack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-packs/complex-python-codeql-pack/rootAndBar.qls

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

以下配置文件仅运行生成严重性错误警报的查询。该配置首先选择所有默认查询、./my-queries 中的所有查询以及 codeql/java-queries 中的默认套件，然后排除生成警告或建议的所有查询。

queries:
  - name: Use an in-repository CodeQL query pack (run queries in the my-queries directory)
    uses: ./my-queries
packs:
  - codeql/java-queries
query-filters:
- exclude:
    problem.severity:
      - warning
      - recommendation

使用 `config` 输入指定配置详细信息

如果你希望在工作流文件中指定其他配置详细信息，可以使用 CodeQL 操作的 init 命令的 config 输入。此输入的值必须是 YAML 字符串，遵循上述“使用自定义配置文件”中所述的配置文件格式。

配置示例

GitHub Actions 工作流文件中的这一步骤使用 config 输入来禁用默认查询、添加 security-extended 查询套件，并排除标记为 cwe-020 的查询。

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

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

Tip

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

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

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

为编译语言配置 code scanning

对于已编译语言，CodeQL 操作生成代码库以创建要分析的 CodeQL 数据库。默认情况下，CodeQL 使用步骤 autobuild 来确定代码库最有可能的生成方法。如果 autobuild 失败，或想要分析 autobuild 进程生成的版本中源文件的不同集合，则需要在工作流中删除或注释禁止自动生成步骤。然后取消注释步骤 run 并手动指定要使用的生成进程。如果是 C/C++、C#、Go、Java、Kotlin 和 Swift，CodeQL 会分析指定的生成步骤生成的所有源代码。有关如何为编译语言配置 CodeQL code scanning 的详细信息，请参阅“对编译语言进行 CodeQL 代码扫描”。

将 code scanning 数据上传到 GitHub

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

自定义代码扫描的高级设置

谁可以使用此功能？

本文内容

关于 code scanning 配置

编辑 code scanning 工作流

配置频率

按推送扫描

扫描拉取请求

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

按时间表扫描

示例

指定操作系统

指定 CodeQL 数据库的位置

更改分析的语言

定义导致拉取请求检查失败的警报严重性

配置分析类别

在使用 CodeQL 模型包扩展 CodeQL 覆盖范围

运行额外查询

使用查询包

从 GitHub Enterprise Server 下载 CodeQL 包

在 QL 包中使用查询

使用自定义配置文件

使用自定义配置文件

指定 CodeQL 查询包

指定额外查询

禁用默认查询

从分析中排除特定查询

指定要扫描的目录

示例配置文件

使用 `config` 输入指定配置详细信息

配置示例

为编译语言配置 code scanning

将 code scanning 数据上传到 GitHub