Создание пакетов CodeQL и работа с ними

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

Примечание: Функции управления пакетами CodeQL, включая пакеты CodeQL, в настоящее время доступны в виде бета-версии и могут быть изменены. Во время бета-версии пакеты CodeQL доступны только с помощью пакетов GitHub — Container registry. Чтобы использовать эту бета-версию, установите последнюю версию пакета CodeQL CLI из: https://github.com/github/codeql-action/releases.

Сведения о пакетах CodeQL и CodeQL CLI

С помощью пакетов CodeQL и команд управления пакетами в CodeQL CLI можно публиковать пользовательские запросы и интегрировать их в анализ базы кода.

Существует два типа пакетов CodeQL: пакеты запросов и пакеты библиотек.

Пакеты запросов предназначены для выполнения. При публикации пакета запроса пакет включает все транзитивные зависимости и предварительно скомпилированные представления каждого запроса в дополнение к источникам запросов. Это обеспечивает согласованное и эффективное выполнение запросов в пакете.
Пакеты библиотек предназначены для использования пакетами запросов (или другими пакетами библиотек) и не содержат сами запросы. Библиотеки не компилируются отдельно.

Вы можете использовать pack команду в CodeQL CLI для создания пакетов CodeQL, добавления зависимостей в пакеты, установки или обновления зависимостей. Вы также можете опубликовать и скачать пакеты CodeQL с помощью pack команды . Дополнительные сведения см. в разделе Публикация и использование пакетов CodeQL.

Дополнительные сведения о совместимости между опубликованными пакетами запросов и различными выпусками CodeQL см. в разделе Сведения о совместимости пакетов CodeQL.

Создание пакета CodeQL

Вы можете создать пакет CodeQL, выполнив следующую команду в корневом каталоге оформления проекта:

codeql pack init <scope>/<pack>

Необходимо указать следующие данные:

<scope>: имя организации или учетной записи пользователя GitHub, в которую вы будете публиковаться.
<pack>: имя создаваемого пакета.

Команда codeql pack init создает структуру каталогов и файлы конфигурации для пакета CodeQL. По умолчанию команда создает пакет запроса. Если вы хотите создать пакет библиотеки, необходимо изменить qlpack.yml файл, чтобы явно объявить файл как пакет библиотеки, включив library:true свойство .

Изменение существующего устаревшего пакета QL для создания пакета CodeQL

Если у вас уже есть qlpack.yml файл, его можно изменить вручную, чтобы преобразовать его в пакет CodeQL.

Измените name свойство таким образом, чтобы оно соответствовало формату <scope>/<name>, где <scope> — имя организации или учетной записи пользователя GitHub, в которую вы будете публиковаться.
qlpack.yml Добавьте version в файл свойство с идентификатором semver, а также необязательный dependencies блок.
Перенесите список зависимостей в libraryPathDependencies dependencies блок. Укажите диапазон версий для каждой зависимости. Если диапазон не имеет значения или вы не уверены в совместимости, можно указать "\*", который указывает, что любая версия допустима и будет по умолчанию установлена последняя версия при запуске codeql pack install.

Дополнительные сведения о свойствах см. в разделе Сведения о пакетах CodeQL.

Добавление и установка зависимостей в пакет CodeQL

Вы можете добавить зависимости в пакеты CodeQL с помощью команды codeql pack add. Необходимо указать область, имя и (необязательно) совместимый диапазон версий.

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 установит зависимости из Container registry на GitHub.com. Вы можете установить зависимости из GitHub Enterprise Server Container registry, создав qlconfig.yml файл. Дополнительные сведения см. в разделе Публикация и использование пакетов CodeQL.

Настройка загруженного пакета CodeQL

Рекомендуемый способ поэкспериментировать с изменениями в пакете — клонировать репозиторий, содержащий его исходный код.

Если исходный репозиторий недоступен и вам нужно создать изменения на основе пакета, загруженного из Container registry, имейте в виду, что эти пакеты не предназначены для изменения или настройки после скачивания, и их формат может измениться в будущем без особого уведомления. Если вам нужно изменить содержимое, после скачивания пакета рекомендуется выполнить следующие действия:

Измените имя пакета в , qlpack.yml чтобы избежать путаницы с результатами неизмененных пакетов.
Удалите все файлы с именами *.qlx в любом месте распакованой структуры каталогов. Эти файлы содержат предварительно скомпилированные версии запросов, и в некоторых случаях CodeQL будет использовать их в качестве предпочтительного источника QL, который вы изменили.