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

Примечание: Эта статья была перенесена с веб-сайта документации CodeQL в январе 2023 г.

Сведения о рабочих областях 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.

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

В этой статье