Workspaces CodeQL

О CodeQL рабочих местах

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

Рабочие пространства обычно хранятся в одном репозитории Git, чтобы связанные паки можно было разрабатывать и публиковать вместе.

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

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

Потому что рабочие пакеты разрешаются из источника:

• Локальные изменения в одном наборе сразу видны другим наборам в рабочем пространстве.
• Зависимости, найденные в рабочем пространстве, переопределяют версии в кэше пакетов.
• Ограничения по версиям в qlpack.yml файлах игнорируются в зависимости от рабочего пространства, так как версия определяется содержимым рабочего пространства.

Это поведение особенно полезно при одновременной разработке нескольких связанных пакетов. Рассмотрим пример.

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

Вне рабочего пространства зависимости разрешаются из кэша пакета и должны соответствовать ограничениям версии, определённым в qlpack.yml. Внутри рабочего пространства резолюция отдаёт приоритет локальному исходному контенту.

CodeQL Рабочие пространства и разрешение запросов

Модель зависимости рабочего пространства влияет на то, как пакеты устанавливаются и публикуются.

• Во время установки зависимости, найденные в рабочем пространстве, не загружаются в кэш пакета и не записываются в codeql-pack.lock.yml файл.
• Во время публикации зависимости, предоставляемые рабочим пространством, объединяются с использованием локального исходного контента, а не версий из кэша пакетов.

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

Example

Рабочее CodeQL пространство определяется YAML-файлом с именем codeql-workspace.yml. Рассмотрим следующий файл codeql-workspace.yml:

provide:
  - "**/qlpack.yml"

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

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

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

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

Обратите внимание, что dependencies блок для CodeQL пакета запросов, my-company/my-queries, указывает "*" как версию библиотечного пака. Так как пакет библиотеки уже определен как зависимость источника 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-workspace.yml файла

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

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

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

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

Каждая запись в 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 pack ls их в каталоге workspace.

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

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

Example

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

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 все совместимы с этим пакетом библиотеки.