исправление замечаний
25 KiB
Jenkins shared library for 1C:Enterprise 8
Цель
Создание библиотеки (или плагина) для Jenkins, позволяющей:
- максимально упростить написание Jenkinsfile для процесса CI в условиях платформы 1С:Предприятие 8
- иметь схожий и контролируемый пайплайн для всех проектов
- дать пользователю в руки простой декларативный конфигурационный файл, вместо требования описывать всю сложную логику по работе с 1С
Общие положения
- в активной разработке и поиске "своего пути" по разработке библиотеки;
- формат конфигурационного файла не стабилизирован;
- обратная совместимость пока не гарантируется, внимательно читайте changelog;
- количество stage будет со временем увеличиваться;
- использовать на свой страх и риск;
- любая помощь приветствуется.
Ограничения
- Для шага подготовки требуется любой агент с меткой
agent
. - Для запуска шага анализа SonarQube требуется агент с меткой
sonar
. - Для запуска шагов, работающих с EDT (валидация, трансформация формата исходников) требуется агент с меткой
edt
(если используется несколько версий EDT необходимо к метке добавить версию, напримерedt@2021.3.4:x86_64
) и агент с меткойoscript
, на котором глобально установлена библиотека stebi версии 1.9.1 или новее. - Для запуска шагов, работающих с 1С (подготовка, синтаксический контроль и т.д.) требуется агент с меткой, совпадающей со значением в поле
v8version
файла конфигурации. - В качестве ИБ используется файловая база, создаваемая в каталоге
./build/ib
. При необходимости вы можете создать пользователей на фазе инициализации ИБ.
Возможности
- Все шаги можно запустить на базе docker-образов из https://github.com/firstBitMarksistskaya/onec-docker. См. памятку по слоям и последовательности сборки.
- Поддержка как формата выгрузки из Конфигуратора, так и формата EDT.
- Подготовка информационной базы по версии из хранилища конфигурации, из исходных файлов конфигурации, комбинированный режим (основная ветка - из хранилища, остальные - из исходников).
- Подготовка и загрузка расширений конфигурации из исходных файлов расширения, из cfe-файлов.
- Запуск ИБ в режиме выполнения обработчиков обновления БСП.
- Дополнительные шаги инициализации данных в ИБ.
- Трансформация кода из формата конфигуратора в формат EDT.
- Трансформация кода из формата EDT в формат конфигуратора.
- Запуск BDD сценариев с сохранением результатов в формате Allure.
- Запуск юнит-тестов с помощью фреймворка YAXUnit с сохранением результатов в формате jUnit и Allure.
- Запуск синтаксического контроля средствами конфигуратора и сохранение результатов в виде отчета jUnit.
- Запуск валидации проекта средствами EDT и конвертация отчета в формате generic issues.
- Запуск статического анализа для SonarQube.
- Публикация результатов junit и Allure в интерфейс Jenkins.
- Рассылка результатов сборки на почту и в Telegram.
- Конфигурирование логгера запускаемых oscript-приложений.
Подключение
Инструкция по подключению библиотеки: https://jenkins.io/doc/book/pipeline/shared-libraries/#using-libraries
Примеры Jenkinsfile
Если в настройках подключения shared-library включен флаг "Load implicitly":
pipeline1C()
В обратном случае:
@Library('jenkins-lib') _
pipeline1C()
Да, вот и весь пайплайн. Конфигурирование через json.
Внешний вид пайплайна в интерфейсе Blue Ocean
Конфигурирование
По умолчанию применяется файл конфигурации из ресурсов библиотеки
Поверх него накладывается конфигурация из файла jobConfiguration.json
в корне проекта, если он присутствует.
Пример переопределения:
- указывается точная версия платформы (и соответственно метка агента, см. ограничения)
- указывается точная версия модуля EDT (и соответственно метка агента, см. ограничения)
- идентификаторы credentials для пути к хранилищу и к паре логин/пароль для авторизации в хранилище (необходимы, если применяются шаги, работающие с информационной базой)
- включаются шаги запуска статического анализа SonarQube, валидации средствами EDT и синтаксического контроля
{
"$schema": "https://raw.githubusercontent.com/firstBitMarksistskaya/jenkins-lib/master/resources/schema.json",
"v8version": "8.3.14.1976",
"edtVersion": "2021.3.4:x86_64",
"secrets": {
"storagePath": "f7b21c02-711a-4883-81c5-d429454e3f8b",
"storage" : "c1fc5f33-67d4-493f-a2a4-97d3040e4b8c"
},
"stages": {
"sonarqube": true,
"edtValidate": true,
"syntaxCheck": true
}
}
Параметры по умолчанию
В библиотеке применяется принцип "соглашения по конфигурации" (convention over configuration): конфигурационный файл содержит ряд настроек "по умолчанию". При соблюдении определенных правил структуры репозитория можно сократить количество переопределений конфигурационного файла до минимума. Ниже представлены имеющиеся соглашения и способы их переопределения.
- Общее:
- В качестве маски версии платформы используется строка "8.3" (
v8version
). - По умолчанию версия модуля EDT не заполнена, т.к. в случае единственной версии для утилиты ring дополнительного указания не требуется (
edtVersion
). - Исходники конфигурации ожидаются в каталоге
src/cf
(srcDir
). - Формат исходников - выгрузка из Конфигуратора (
sourceFormat
). - Ветка по умолчанию (для комбинированного режима загрузки конфигурации) - "main" (
defaultBranch
). - Имена большинства "секретов" (jenkins credentials,
secrets
) по умолчанию высчитываются из пути к git-репозиторию (без учета домена, с заменой/
на_
) с прибавлением ключа секрета. Например, для репозитория https://github.com/firstBitSemenovskaya/jenkins-lib секрет с адресом хранилища будет выглядеть какfirstBitSemenovskaya_jenkins-lib_STORAGE_PATH
. Ключи секретов:STORAGE_PATH
- путь к хранилищу конфигурации (дляsecrets
->storagePath
);STORAGE_USER
- параметры авторизации в хранилище вида "username with password" (дляsecrets
->storage
).TELEGRAM_CHAT_ID
- идентификатор чата Telegram для рассылки уведомлений и результате сборки вида "secret text" (дляsecrets
->telegramChatId
).
- Секрет
TELEGRAM_BOT_TOKEN
задается глобально на весь сервер Jenkins, либо может быть переопределен (secrets
->telegramBotToken
) - Все "шаги" по умолчанию выключены (
stages
). - Если в корне репозитория существует файл
packagedef
, то в шагах, работающих с информационной базой, будет выполнена попытка установки локальных зависимостей средствамиopm
. - Если после установки локальных зависимостей в каталоге
oscript_modules/bin
существует файлvrunner
, то для выполнения команд работы с информационной базой будет использоваться он, а не глобально установленныйvrunner
изPATH
. - Результаты в формате
allure
ожидаются в каталогеbuild/out/allure
или его подкаталогах. - Каждый шаг имеет свой таймаут в минутах (от 10 до 240 в зависимости от "тяжёлости" шага сборки), но может быть переопределен в секции настроек
timeout
.
- В качестве маски версии платформы используется строка "8.3" (
- Инициализация:
- Информационная база инициализируется только в том случае, если в сборочной линии включены шаги, работающие с базой (например,
bdd
илиsyntaxCheck
). - Информационная база инициализируется конфигурацией из хранилища конфигурации (
initInfobase
->initMethod
). - Если выбран метод инициализации ИБ из хранилища конфигурации и в каталоге исходников есть файл
VERSION
(артефакт от работы утилитыgitsync
), то из хранилища будет загружена версия конфигурации с номером из файлаVERSION
.
- Информационная база инициализируется только в том случае, если в сборочной линии включены шаги, работающие с базой (например,
- Первичный запуск информационной базы:
- Если информационная база нужна для запуска в режиме "Предприятие" (например, для шагов
bdd
илиsmoke
), то будет запущен шаг "Миграция ИБ". - После загрузки конфигурации в ИБ будет выполняться запуск ИБ с целью запуска обработчиков обновления из БСП (
initInfobase
->runMigration
). - Если в настройках шага инициализации не заполнен массив дополнительных шагов миграции (
initInfobase
->additionalInitializationSteps
), но в каталогеtools
присутствуют файлы с именами, удовлетворяющими шаблонуvrunner.init*.json
, то автоматически выполняется запускvrunner vanessa
с передачей найденных файлов в качестве значения настроек (параметр--settings
) в порядке лексикографической сортировки имен файлов.
- Если информационная база нужна для запуска в режиме "Предприятие" (например, для шагов
- BDD:
- Если в конфигурационном файле проекта не заполнена настройка
bdd
->vrunnerSteps
, то автоматически выполняется запускvrunner vanessa --settings tools/vrunner.json
.
- Если в конфигурационном файле проекта не заполнена настройка
- YAXUnit:
- Если в репозитории существует файл
tools/yaxunit.json
, то он будет передан в качестве параметра для YAXUnit при запуске тестов. Если файла с таким именем нет, то в YAXUnit будет передан файл из текущей библиотекиresources/yaxunit.json
. Он содержит минимально необходимые параметры и настроен на поиск сценариев в расширении с именемYAXUnit
.
- Если в репозитории существует файл
- Дымовые тесты:
- Если в репозитории существует файл
tools/vrunner.json
, то запуск дымовых тестов будет выполняться с передачей файла в параметры запускаvrunner xunit --settings tools/vrunner.json
(smoke
->vrunnerSettings
). - Если установка локальных зависимостей
opm
установит пакетadd
, то будет использоваться обработкаxddTestRunner.epf
из локальных зависимостей. - Если в репозитории существует файл
tools/xUnitParams.json
, то этот путь к файлу будет передан в параметр запускаvrunner xunit --xddConfig ./tools/xUnitParams.json
(smoke -> xUnitParams
). - Если используемый конфигурационный файл (
vrunner.json
) не содержит настройкуtestsPath
, то запускается полный комплект дымовых тестов, расположенных в$addRoot/tests/smoke
. - По умолчанию включено формирование отчета в формате
jUnit
(smoke
->publishToJUnitReport
) и выключено формирование отчета в формате Allure (smoke
->publishToAllureReport
).
- Если в репозитории существует файл
- Синтаксический контроль:
- Если в репозитории существует файл
tools/vrunner.json
, то синтаксический контроль конфигурации с помощью конфигуратора будет выполняться с передачей файла в параметры запускаvrunner syntax-check --settings tools/vrunner.json
(syntaxCheck
->vrunnerSettings
). - Применяется группировка ошибок по метаданным (
syntaxCheck
->groupErrorsByMetadata
). - Выгрузка результатов в формат
jUnit
осуществляется в файл./build/out/jUnit/syntax.xml
(syntaxCheck
->pathToJUnitReport
). - Если в репозитории существует файл
./tools/syntax-check-exception-file.txt
, то команде запуска синтаксического контроля конфигурации данный файл будет передаваться как файл с исключениями сообщений об ошибках (параметр--exception-file
) (syntaxCheck
->exceptionFile
). - Конфигурационный файл по умолчанию уже содержит ряд "режимов проверки" для синтаксического контроля конфигурации (
syntaxCheck
->checkModes
).
- Если в репозитории существует файл
- Трансформация результатов валидации EDT:
- По умолчанию из результатов анализа исключаются замечания, сработавшие на модулях с включенным запретом редактирования (желтый куб с замком) (параметры
resultsTransform
->removeSupport
иresultsTransform
->supportLevel
).
- По умолчанию из результатов анализа исключаются замечания, сработавшие на модулях с включенным запретом редактирования (желтый куб с замком) (параметры
- Анализ SonarQube:
- Предполагается наличие единственной настройки
SonarQube installation
(sonarqube
->sonarQubeInstallation
). - Используется
sonar-scanner
из переменной окруженияPATH
(sonarqube
->useSonarScannerFromPath
). - Если использование
sonar-scanner
из переменной окруженияPATH
выключено, предполагается наличие настроенного глобального инструментаSonarQube Scanner
с идентификатором инструментаsonar-scanner
(sonarqube
->sonarScannerToolName
). - Применяется расчет аргументов командной строки для работы
branch plugin
или коммерческих версий SonarQube (sonarqube
->branchAnalysisConfiguration
). - Если разработка ведется с использованием подсистемы БСП "Обновление версии ИБ", то в значение параметра
sonar.projectVersion=$configurationVersion
утилитыsonar-scanner
можно передавать версию из созданного общего модуля. Для этого необходимо заполнить параметр (sonarqube
->infoBaseUpdateModuleName
). Если параметр не заполнен, версия передается из корня конфигурации. - По умолчанию шаг анализа не дожидается окончания фонового задания на сервере SonarQube и не анализирует результат прохождения Порога качества (
sonarqube
->waitForQualityGate
). - Если выполнялась валидация EDT, результаты валидации в формате
generic issues
передаются утилитеsonar-scanner
как значение параметраsonar.externalIssuesReportPaths
.
- Предполагается наличие единственной настройки
- Рассылка уведомлений:
- Электронная почта:
- Для отправки используется плагин
email-ext
. Шаблоны сообщений конфигурируются в настройках плагина. - Уведомления о результатах сборки по умолчанию рассылаются только при полном падении сборочной линии (
notifications
->email
->onAlways
,onFailure
,onUnstable
,onSuccess
). - Лог сборки прикладывается к письму при полном падении сборочной линии и при отправке в режиме "всегда отправлять" (
notifications
->email
->*options
->attachLog
). - В качестве получателей писем (
notifications
->email
->*options
->recipientProviders
) в различных режимах отправки используются:- всегда - разработчики и запустивший сборку;
- при падении - разработчики, запустивший сборку и подозреваемый в причине падения сборки;
- при успехе - разработчики и запустивший сборку;
- при нестабильной сборке (упавшие тесты) - разработчики и запустивший сборку.
- Прямые получатели уведомлений не заполнены (
notifications
->email
->*options
->directRecipients
).
- Для отправки используется плагин
- Telegram:
- Уведомления о результатах сборки по умолчанию рассылаются всегда (
notifications
->telegram
->onAlways
,onFailure
,onUnstable
,onSuccess
).
- Уведомления о результатах сборки по умолчанию рассылаются всегда (
- Электронная почта:
Настройка загрузки расширений
Если у вас есть расширения которые необходимо загрузить в базу для проведения тестов и проверок, это можно сделать на этапе подготовки базы.
- При загрузке из исходников расширения должны быть в том же формате(edt или конфигуратора) что и основная конфигурация.
- Для загрузки расширений необходимо описать каждое из них в массиве (
initInfobase
->extensions
)
Для загрузки расширений в информационную базу необходимо выполнить следующие шаги:
- Укажите имя расширения(
extensions
->name
). - Определите метод загрузки для каждого расширения(
extensions
->initMethod
). Поддерживаются два метода загрузки:
fromSource
- загрузка из исходников;fromFile
- загрузка cfe-файла.
- Укажите путь до расширения или URL для скачивания cfe-файла(
extensions
->path
).
- В случае загрузки из исходников - необходимо указать путь к исходникам расширения
- В случае загрузки cfe - Укажите путь по которому будет скачан cfe. На данный момент можно указывать как локальный путь, так и url для скачивания cfe(Прим.: https://github.com/bia-technologies/yaxunit/releases/download/23.05/YAXUNIT-23.05.cfe)
Пример конфигурации для загрузки расширений:
"initInfobase": {
"extensions": [
{
"name": "ИмяРасширения1",
"initMethod": "fromSource",
"path": "путь/до/исходников/расширения"
},
{
"name": "ИмяРасширения2",
"initMethod": "fromFile",
"path": "https://example.com/path/to/extension.cfe"
}
]
}
Настройка шага YAXUnit
- Добавить расширение
YAXUnit
и дополнительные расширения с тестами можно вjobConfiguration.json
->initInfobase
->extensions
. Они будут загружены при инициализации ИБ. - Если ваши тесты размещены в отдельных расширениях, скопируйте файл
./resources/yaxunit.json
из текущей библиотеки в свой репозиторий (./tools/yaxunit.json
) и перечислите в нем имена ваших расширений.