Skip to main content

Сведения о рабочих областях CodeQL

Рабочие области CodeQL позволяют разрабатывать и поддерживать группу пакетов CodeQL, которые зависят друг от друга.

Кто эту функцию можно использовать?

GitHub CodeQL лицензируется на основе каждого пользователя при установке. Вы можете использовать CodeQL только для определенных задач в соответствии с ограничениями лицензии. Дополнительные сведения см. в разделе Сведения о интерфейсе командной строки CodeQL.

Если у вас есть лицензия GitHub Advanced Security, можно использовать CodeQL для автоматического анализа, непрерывной интеграции и непрерывной доставки. Дополнительные сведения см. в разделе Сведения о GitHub Advanced Security.

Сведения о рабочих областях CodeQL

Вы используете рабочую область CodeQL для группирования нескольких пакетов CodeQL . Типичным вариантом использования рабочей области CodeQL является разработка набора библиотеки CodeQL и пакетов запросов, которые являются взаимозависимыми. Дополнительные сведения о пакетах CodeQL см. в разделе "Настройка анализа с помощью пакетов CodeQL".

Основное преимущество рабочей области CodeQL заключается в том, что это упрощает разработку и обслуживание нескольких пакетов CodeQL. При использовании рабочей области CodeQL все пакеты CodeQL в рабочей области доступны в качестве зависимостей источника при выполнении команды CodeQL, разрешающей запросы. Это упрощает разработку, обслуживание и публикацию нескольких связанных пакетов CodeQL.

В большинстве случаев следует хранить рабочую область CodeQL и пакеты CodeQL в одном репозитории Git. Это упрощает совместное использование среды разработки CodeQL.

Файл codeql-workspace.yml

Рабочая область CodeQL определяется yaml-файлом codeql-workspace.yml . Этот файл содержит provide блок и при необходимости ignore и registries блоки.

  • Блок provide содержит список шаблонов глобов, определяющих пакеты CodeQL, доступные в рабочей области.

  • Блок ignore содержит список шаблонов глобов, определяющих пакеты CodeQL, которые недоступны в рабочей области.

  • Блок registries содержит список URL-адресов GHES и шаблонов пакетов, которые управляют тем, какой реестр контейнеров используется для публикации пакетов CodeQL . Дополнительные сведения см. в разделе Публикация и использование пакетов CodeQL.

Каждая запись в provide разделе ignore должна сопоставляться с расположением qlpack.yml файла. Все шаблоны glob определяются относительно каталога, содержащего файл рабочей области. Список шаблонов, принятых в этом файле, см. в разделе "@actions/glob ".

Например, следующий codeql-workspace.yml файл определяет рабочую область, содержащую все пакеты CodeQL, рекурсивно найденные в codeql-packs каталоге, за исключением пакетов в каталоге experimental . Блок registries указывает, что codeql/\* пакеты должны быть скачаны из https://ghcr.io/v2/реестра контейнеров по умолчанию GitHub. Все остальные пакеты следует скачать и опубликовать в реестре GHE_HOSTNAME.

provide:
  - "*/codeql-packs/**/qlpack.yml"
ignore:
  - "*/codeql-packs/**/experimental/**/qlpack.yml"

registries:
 - packages: 'codeql/*'
   url: https://ghcr.io/v2/

 - packages: '*'
   url: https://containers.GHE_HOSTNAME/v2/

Чтобы убедиться, что файл codeql-workspace.yml содержит ожидаемые пакеты CodeQL, выполните codeql pack ls команду в том же каталоге, что и рабочая область. Результатом команды является список всех пакетов CodeQL в рабочей области.

Зависимости источника

Зависимости источника — это пакеты CodeQL, которые разрешаются из локальной файловой системы за пределами кэша пакетов CodeQL. Эти зависимости могут находиться в той же рабочей области CodeQL или указан в качестве варианта пути с помощью аргумента --additional-packs . При локальной компиляции и выполнении запросов зависимости источника переопределяют все зависимости, найденные в кэше пакетов CodeQL, а также ограничения версий, определенные в кэше qlpack.ymlпакетов . Все ссылки на пакеты CodeQL в одной рабочей области разрешаются в качестве зависимостей источника.

Это особенно полезно в следующих ситуациях:

  • Одна из зависимостей запущенного пакета запроса еще не опубликована. Разрешение из источника — единственный способ ссылаться на этот пакет.

  • Вы вносите изменения в несколько пакетов одновременно и хотите протестировать их вместе. Разрешение из источника гарантирует, что вы используете версию пакета с изменениями в нем.

CodeQL рабочих областей и разрешения запросов

Все пакеты CodeQL в рабочей области доступны в качестве зависимостей источника при выполнении любой команды CodeQL, разрешающей запросы или пакеты. Например, при запуске codeql pack install в каталоге пакетов в рабочей области все зависимости, которые можно найти в рабочей области, будут использоваться вместо загрузки этой зависимости в кэш пакетов и добавления его в codeql-pack.lock.yml файл. Дополнительные сведения см. в разделе Создание и работа с пакетами CodeQL.

Аналогичным образом при публикации пакета запросов CodeQL в реестр контейнеров GitHub с помощью codeql pack publish команды всегда будут использоваться зависимости из рабочей области вместо использования зависимостей, найденных в локальном кэше пакетов.

Это гарантирует, что все локальные изменения, внесенные в библиотеку запросов в зависимости, автоматически отражаются в любых пакетах запросов, публикуемых из этой рабочей области.

Пример

Рассмотрим следующий файл codeql-workspace.yml:

provide:
  - "**/qlpack.yml"

И следующий файл пакета библиотеки qlpack.yml CodeQL в рабочей области:

name: my-company/my-library
library: true
version: 1.0.0

И следующий файл пакета qlpack.yml запросов CodeQL в рабочей области:

name: my-company/my-queries
version: 1.0.0
dependencies:
  my-company/my-library: "*"
  codeql/cpp-all: ~0.2.0

Обратите внимание, что dependencies блок для пакета my-company/my-queriesзапросов CodeQL указывает "*" версию пакета библиотеки. Так как пакет библиотеки уже определен как зависимость источника codeql-workspace.yml, содержимое пакета библиотеки всегда разрешается из рабочей области. Любое ограничение версии, указанное вами, будет игнорироваться в этом случае. Рекомендуется использовать "*" для зависимостей источника, чтобы убедиться, что версия наследуется от рабочей области.

При выполнении codeql pack install из каталога пакета запросов соответствующая версия codeql/cpp-all загружается в локальный кэш пакетов. Кроме того, codeql-pack.lock.yml создается файл, содержащий разрешенную версию codeql/cpp-all. Файл блокировки не будет содержать запись my-company/my-library , так как она разрешается из исходных зависимостей. Файл codeql-pack.lock.yml будет выглядеть примерно так:

dependencies:
  codeql/cpp-all:
    version: 0.2.2

При выполнении codeql pack publish из каталога codeql/cpp-all пакета запросов зависимость от кэша пакетов и my-company/my-library рабочей области объединяются и my-company/my-queries публикуются в реестре контейнеров GitHub.

Использование ${workspace} в качестве диапазона версий в файлах qlpack.yml

Пакеты CodeQL в рабочей области могут использовать специальные ${workspace}``~${workspace}``^${workspace} заполнители и диапазон версий. Эти заполнители указывают, что этот пакет зависит от версии указанного пакета, который в настоящее время находится в рабочей области. Этот заполнитель обычно используется для зависимостей внутри пакетов библиотек, чтобы гарантировать, что при публикации зависимости в файле qlpack.yml отражают состояние рабочей области при их публикации.

Пример

Рассмотрим следующие два пакета библиотеки в одной рабочей области:

name: my-company/my-library
library: true
version: 1.2.3
dependencies:
  my-company/my-library2: ${workspace}
name: my-company/my-library2
library: true
version: 4.5.6

При my-company/my-library публикации в реестре контейнеров GitHub версия зависимости my-company/my-library2 в опубликованном qlpack.yml файле будет записана как 4.5.6.

Аналогичным образом, если зависимость находится my-company/my-library2: ^${workspace} в исходном пакете, а затем будет опубликован пакет, версия my-company/my-library2 зависимости в опубликованном qlpack.yml файле будет записана как ^4.5.6, указывающая, что версии >= 4.5.6 и < 5.0.0 все совместимы с этим пакетом библиотеки.

Если зависимость находится my-company/my-library2: ~${workspace} в исходном пакете, а затем будет опубликован пакет, версия my-company/my-library2 зависимостей в опубликованном qlpack.yml файле будет записана как ~4.5.6, указывающая, что версии >= 4.5.6 и < 4.6.0 все совместимы с этим пакетом библиотеки.