此版本的 GitHub Enterprise Server 已于以下日期停止服务 2024-03-26. 即使针对重大安全问题，也不会发布补丁。 为了获得更好的性能、更高的安全性和新功能，请升级到最新版本的 GitHub Enterprise。 如需升级帮助，请联系 GitHub Enterprise 支持。

创建并使用 CodeQL 包

可以使用 CodeQL 包创建、共享、依赖和运行 CodeQL 查询和库。

谁可以使用此功能？

GitHub CodeQL 在安装后按用户授权。 根据许可证限制，只能将 CodeQL 用于某些任务。 有关详细信息，请参阅“关于 CodeQL CLI”。

如果你有 GitHub Advanced Security 许可证，则可以使用 CodeQL 进行自动分析、持续集成和持续交付。 有关详细信息，请参阅“关于 GitHub 高级安全性”。

本文内容

注意：CodeQL 包管理功能（包括 CodeQL 包）当前提供 beta 版本，可能会发生更改。 在 beta 版本发布期间，CodeQL 包只能使用 GitHub 包，即 Container registry。 若要使用此 beta 版功能，请安装最新版本的 CodeQL CLI 捆绑包： https://github.com/github/codeql-action/releases 。

关于 CodeQL 包和 CodeQL CLI

注意：本文介绍了 GitHub Enterprise Server 3.8 的初始发行版中包含的 CodeQL CLI 2.12.7 捆绑包中可用的功能。

如果站点管理员已将 CodeQL CLI 版本更新为较新版本，请参阅本文的 GitHub Enterprise Cloud 版本，了解有关最新功能的信息。

CodeQL 包用于创建、共享、依赖和运行 CodeQL 查询和库。 CodeQL 包中具有查询、库文件、查询套件和元数据。 使用 CodeQL 包和 CodeQL CLI 中的包管理命令，可以发布自定义查询并将其集成到代码库分析中。

有两种类型的 CodeQL 包：查询包和库包。

  • 查询包专为运行设计。 发布查询包时，此捆绑包中具有每个查询的所有可传递依赖项和编译缓存。 这可确保一致且高效地执行包中的查询。

  • 库包旨在供查询包（或其他库包）使用，并且不包含查询本身。 库不可编译，并且在发布包时不包含编译缓存。

可以使用 CodeQL CLI 中的 pack 命令创建 CodeQL 包、向包添加依赖项以及安装或更新依赖项。 还可以使用 pack 命令发布和下载 CodeQL 包。 有关详细信息，请参阅“发布及使用 CodeQL 包”。

所有受支持语言的标准 CodeQL 包在 Container registry 中发布。 CodeQL 存储库包含所有受支持语言的标准 CodeQL 包的源文件。 CodeQL CLI 捆绑包中包含的但可以以其他方式下载的核心查询包包括：

  • codeql/cpp-queries
  • codeql/csharp-queries
  • codeql/go-queries
  • codeql/java-queries
  • codeql/javascript-queries
  • codeql/python-queries
  • codeql/ruby-queries

CodeQL 包结构

CodeQL 包的根目录中必须包含名为 qlpack.yml 的文件。 在 qlpack.yml 文件中，name: 字段必须具有采用 <scope>/<pack> 格式的值，其中 <scope> 是包将发布到的 GitHub 组织或用户帐户，<pack> 是包的名称。 此外，具有 CodeQL 测试的查询包和库包一个中有一个 codeql-pack.lock.yml 文件，该文件中有包的已解析依赖项。 此文件是在调用 codeql pack install 命令期间生成的，不应手动编辑，并且应将其添加到版本控制系统中。

包内的其他文件和目录应按逻辑组织。 例如，通常：

  • 查询按特定类别组织到目录中。

  • 对特定产品、库和框架的查询组织为其自己的顶级目录。

创建 CodeQL 包

可以通过从项目的签出根运行以下命令来创建 CodeQL 包：

codeql pack init <scope>/<pack>

必须指定以下内容：

  • <scope>：将发布到的 GitHub 组织或用户帐户的名称。

  • <pack>：正在创建的包的名称。

codeql pack init 命令为 CodeQL 包创建目录结构和配置文件。 默认情况下，此命令会创建查询包。 如果要创建库包，必须编辑 qlpack.yml 文件，通过包含 library:true 属性将文件显式声明为库包。

修改现有的旧版 QL 包以创建 CodeQL 查询包

如果已有 qlpack.yml 文件，可以手动编辑它，将其转换为 CodeQL 包。

  1. 编辑 name 属性，使其与格式 <scope>/<name> 匹配，其中 <scope> 是要发布到的 GitHub 组织或用户帐户的名称。

  2. 在 qlpack.yml 文件中，包括一个具有 semver 标识符的 version 属性，以及一个可选的 dependencies 块。

  3. 将 libraryPathDependencies 中的依赖项列表迁移到 dependencies 块。 为每个依赖项指定版本范围。 如果范围不重要，或者你不确定兼容性，则可以指定 "\*"，这指示任何版本都是可接受的，并在运行 codeql pack install 时默认为最新版本。

有关这些属性的详细信息，请参阅“使用 CodeQL 包自定义分析”。

在 CodeQL 包中添加和安装依赖项

注意： 仅 CodeQL 查询包和库包支持此功能。

可以使用命令 codeql pack add 添加对 CodeQL 包的依赖项。 必须指定范围、名称和（可选）兼容版本范围。

codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>

如果未指定版本范围，则将添加最新版本。 否则，将添加满足所请求范围的最新版本。

此命令使用请求的依赖项更新 qlpack.yml 文件，并将其下载到包缓存中。 请注意，此命令将重新格式化文件并删除所有注释。

还可以手动编辑 qlpack.yml 文件以包含依赖项，并使用以下命令安装依赖项：

codeql pack install

此命令将所有依赖项下载到本地磁盘上的共享缓存。

注意：

  • 运行 codeql pack add 和 codeql pack install 命令将生成或更新 codeql-pack.lock.yml 文件。 此文件应签入版本控制。 codeql-pack.lock.yml 文件包含包使用的确切版本号。 有关详细信息，请参阅“关于 codeql-pack.lock.yml 文件”。

  • 默认情况下，codeql pack install 将在 GitHub.com 上安装来自 Container registry 的依赖项。 可以通过创建 qlconfig.yml 文件从 GitHub Enterprise Server Container registry 安装依赖项。 有关详细信息，请参阅 GitHub Enterprise Server 文档中的“发布及使用 CodeQL 包”。