Skip to main content

为编译的语言配置 CodeQL 工作流

可以配置 GitHub 如何使用 CodeQL analysis workflow 扫描用编译语言编写的代码以查找漏洞和错误。

Who can use this feature

If you have write permissions to a repository, you can configure code scanning for that repository.

Code scanning 可用于 GitHub Enterprise Server 中的组织拥有的存储库。 此功能需要 GitHub Advanced Security 的许可证。 有关详细信息,请参阅“关于 GitHub Advanced Security”。

Note: Your site administrator must enable code scanning for your GitHub Enterprise Server instance 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 code scanning for your appliance."

关于 CodeQL analysis workflow 和编译语言

通过添加 GitHub Actions 工作流程到仓库,设置 GitHub 对仓库运行 code scanning。 对于 CodeQL code scanning,可以添加 CodeQL analysis workflow。 有关详细信息,请参阅“为存储库设置 code scanning”。

一般情况下无需编辑 code scanning 的默认工作流程。 但是,如果需要,您可以编辑工作流程以自定义某些设置。 例如,可以编辑 GitHub 的 CodeQL analysis workflow 来指定扫描频率、要扫描的语言或目录,以及 CodeQL code scanning 在代码中查找的内容。 如果使用一组特定的命令来编译代码,可能还需要编辑 CodeQL analysis workflow。 有关配置 code scanning 和编辑工作流文件的一般信息,请参阅“配置 code scanning ”和“了解 GitHub Actions”。

关于 CodeQL 的自动构建

Code scanning 的工作原理是针对一个或多个数据库运行查询。 每个数据库都包含仓库中所有代码的单一语言表示形式。
对于编译语言 C/C++、C#、和 Java,填充此数据库的过程涉及构建代码和提取数据。 对于这些语言,CodeQL 分析生成的存储库中的源文件。 对于上述任何语言,可以禁用 autobuild 并改用自定义生成命令,以仅分析这些自定义命令生成的文件。

对于受支持的编译语言,你可使用 CodeQL analysis workflow 中的 autobuild 操作来生成代码。 这样就无需为 C/C++、C#、和 Java 指定显式生成命令。

如果你的工作流使用 language 矩阵,autobuild 会尝试生成矩阵中列出的每种编译语言。 如果不使用矩阵,则 autobuild 会尝试生成在存储库中具有最多源文件的受支持编译语言。 除 Go 以外,除非您提供明确的构建命令,否则您仓库中其他编译语言的分析将失败。

注意:如果使用 GitHub Actions 的自承载运行器,则可能需要安装其他软件才能使用 autobuild 进程。 此外,如果您的仓库需要特定版本的构建工具,您可能需要手动安装它。 有关详细信息,请参阅“GitHub 托管的运行器的规范”。

C/C++

支持的系统类型系统名称
操作系统Windows、macOS 和 Linux
构建系统Windows:MSbuild 和生成脚本
Linux 和 macOS:Autoconf、Make、CMake、qmake、Meson、Waf、SCons、Linux Kbuild 和生成脚本

autobuild 步骤的行为因运行提取的操作系统而异。 在 Windows 上,autobuild 步骤尝试使用以下方法自动检测适合 C/C++ 的生成方法:

  1. 对离根最近的解决方案 (.sln) 或项目 (.vcxproj) 文件调用 MSBuild.exe。 如果 autobuild 在顶层目录下的相同(最短)深度检测到多个解决方案或项目文件,它将尝试生成所有这些文件。
  2. 调用看起来像生成脚本的脚本:build.bat、build.cmd 和 build.exe(按此顺序) 。

在 Linux 和 macOS 上,autobuild 步骤检查存储库中存在的文件,以确定使用的生成系统:

  1. 在根目录中查找构建系统。
  2. 如果未找到,则搜索子目录以查找含有 C/C++ 构建系统的唯一目录。
  3. 运行适当的命令来配置系统。

C#

支持的系统类型系统名称
操作系统Windows 和 Linux
构建系统.NET 和 MSbuild,以及构建脚本

autobuild 进程尝试使用以下方法自动检测适合 C# 的构建方法:

  1. 对离根最近的解决方案 (.sln) 或项目 (.csproj) 文件调用 dotnet build
  2. 对离根最近的解决方案或项目文件调用 MSbuild (Linux) 或 MSBuild.exe (Windows)。 如果 autobuild 在顶层目录下的相同(最短)深度检测到多个解决方案或项目文件,它将尝试生成所有这些文件。
  3. 调用看起来像生成脚本的脚本:build 和 build.sh(对于 Linux,按此顺序)或 build.bat、build.cmd 和 build.exe(对于 Windows,按此顺序) 。

Java

支持的系统类型系统名称
操作系统Windows、macOS 和 Linux(无限制)
构建系统Gradle、Maven 和 Ant

autobuild 进程尝试通过应用此策略来确定 Java 代码库的生成系统:

  1. 在根目录中搜索构建文件。 先后检查 Gradle、Maven 和 Ant 构建文件。
  2. 运行找到的第一个构建文件。 如果 Gradle 和 Maven 文件都存在,则使用 Gradle 文件。
  3. 否则,在根目录的直接子目录中搜索构建文件。 如果只有一个子目录包含构建文件,则运行该子目录中标识的第一个文件(使用与 1 相同的首选项)。 如果多个子目录包含构建文件,则报告错误。

添加编译语言的构建步骤

如果 autobuild 失败,或者你想要分析与 autobuild 进程生成的源文件不同的一组源文件,则需要从工作流中删除 autobuild 步骤,并手动添加生成步骤。 对于 C/C++、C#、Go、和 Java 项目,CodeQL 将分析由指定的生成步骤生成的任何源代码。 有关如何编辑工作流文件的信息,请参阅“配置 code scanning”。

删除 autobuild 步骤后,取消注释 run 步骤并添加适合存储库的生成命令。 工作流 run 步骤会使用操作系统的 shell 来运行命令行程序。 可以修改这些命令并添加更多命令以自定义生成过程。

- run: |
    make bootstrap
    make release

有关 run 关键字的详细信息,请参阅“GitHub Actions 的工作流语法”。

如果存储库包含多个编译语言,可以指定特定于语言的生成命令。 例如,如果存储库包含 C/C++、C# 和 Java,而 autobuild 正确生成了 C/C++ 和 C#,但未能生成 Java,那么在 init 步骤之后,可以在工作流中使用以下配置。 这指定了 Java 的生成步骤,同时仍然为 C/C++ 和 C# 使用 autobuild

- if: matrix.language == 'cpp' || matrix.language == 'csharp' 
  name: Autobuild
  uses: github/codeql-action/autobuild@v2

- if: matrix.language == 'java' 
  name: Build Java
  run: |
    make bootstrap
    make release

有关 if 条件的详细信息,请参阅“GitHub Actions 的工作流语法”。

有关为什么 autobuild 无法生成代码的更多提示和技巧,请参阅“CodeQL 工作流故障排除”。

如果您为编译语言添加了手动构建步骤,但 code scanning 仍然无法处理您的仓库,请联系 你的网站管理员。