Сведения о рабочих областях CodeQL
Примечание. В этой статье описываются функции, доступные в версии действия CodeQL и связанного пакета CodeQL CLI в первоначальном выпуске этой версии GitHub Enterprise Server. Если ваше предприятие использует более последнюю версию действия CodeQL, ознакомьтесь с версией GitHub Enterprise Cloud этой статьи, чтобы узнать о последних функциях. Сведения об использовании последней версии см. в разделе "Настройка сканирования кода для устройства".
Вы используете рабочую область 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
все совместимы с этим пакетом библиотеки.