Jenkins shared library for 1C:Enterprise 8

Цель

Создание библиотеки (или плагина) для Jenkins, позволяющей:

максимально упростить написание Jenkinsfile для процесса CI в условиях платформы 1С:Предприятие 8
иметь схожий и контролируемый пайплайн для всех проектов
дать пользователю в руки простой декларативный конфигурационный файл, вместо требования описывать всю сложную логику по работе с 1С

Общие положения

в активной разработке и поиске "своего пути" по разработке библиотеки;
формат конфигурационного файла не стабилизирован;
обратная совместимость пока не гарантируется, внимательно читайте changelog;
количество stage будет со временем увеличиваться;
использовать на свой страх и риск;
любая помощь приветствуется.

Ограничения

Для шага подготовки требуется любой агент с меткой agent.
Для запуска шага анализа SonarQube требуется агент с меткой sonar.
Для запуска шагов, работающих с EDT (валидация, трансформация формата исходников) требуется агент с меткой edt и агент с меткой oscript (для трансформации результатов с помощью библиотеки stebi).
Для запуска шагов, работающих с 1С (подготовка, синтаксический контроль и т.д.) требуется агент с меткой, совпадающей со значением в поле v8version файла конфигурации.
В качестве ИБ используется файловая база, создаваемая в каталоге ./build/ib. При необходимости вы можете создать пользователей на фазе инициализации ИБ.
Шаг "Дымовые тесты" пока пустой.

Возможности

Все шаги можно запустить на базе docker-образов из форка репозитория onec-docker. См. памятку по слоям и последовательности сборки.
Поддержка как формата выгрузки из Конфигуратора, так и формата EDT.
Подготовка информационной базы по версии из хранилища конфигурации, из исходных файлов конфигурации, комбинированный режим (основная ветка - из хранилища, остальные - из исходников).
Запуск ИБ в режиме выполнения обработчиков обновления БСП.
Дополнительные шаги инициализации данных в ИБ.
Трансформация кода из формата конфигуратора в формат EDT.
Трансформация кода из формата EDT в формат конфигуратора.
Запуск BDD сценариев с сохранением результатов в формате Allure.
Запуск синтаксического контроля средствами конфигуратора и сохранение результатов в виде отчета jUnit.
Запуск валидации проекта средствами EDT и конвертация отчета в формате generic issues.
Запуск статического анализа для SonarQube.
Публикация результатов junit и Allure в интерфейс Jenkins.
Конфигурирование логгера запускаемых 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 в корне проекта, если он присутствует.

Пример переопределения:

указывается точная версия платформы (и соответственно метка агента, см. ограничения)
идентификаторы credentials для пути к хранилищу и к паре логин/пароль для авторизации в хранилище (необходимы, если применяются шаги, работающие с информационной базой)
включаются шаги запуска статического анализа SonarQube, валидации средствами EDT и синтаксического контроля

{
    "$schema": "https://raw.githubusercontent.com/firstBitSemenovskaya/jenkins-lib/master/resources/schema.json",
    "v8version": "8.3.14.1976",
    "secrets": {
        "storagePath": "f7b21c02-711a-4883-81c5-d429454e3f8b",
        "storage" : "c1fc5f33-67d4-493f-a2a4-97d3040e4b8c"
    },
    "stages": {
        "sonarqube": true,
        "edtValidation": true,
        "syntaxCheck": true
    }
}

Параметры по умолчанию

В библиотеке применяется принцип "соглашения по конфигурации" (convention over configuration): конфигурационный файл содержит ряд настроек "по умолчанию". При соблюдении определенных правил структуры репозитория можно сократить количество переопределений конфигурационного файла до минимума. Ниже представлены имеющиеся соглашения и способы их переопределения.

Общее:
- В качестве маски версии платформы используется строка "8.3" (v8version).
- Исходники конфигурации ожидаются в каталоге src/cf (srcDir).
- Формат исходников - выгрузка из Конфигуратора (sourceFormat).
- Ветка по умолчанию (для комбинированного режима загрузки конфигурации) - "main" (defaultBranch).
- TODO: Имена "секретов" (jenkins credentials, secrets) по умолчанию высчитываются как GROUP_REPO_KEY, где GROUP и REPO - это группа проектов и имя проектов (например, firstBitSemenovskaya и jenkins-lib), а KEY - ключ секрета:
  - STORAGE_PATH - путь к хранилищу конфигурации (secrets -> storagePath);
  - STORAGE_USER - параметры авторизации в хранилище вида "username with password" (secrets -> storage).
- Все "шаги" по умолчанию выключены (stages).
- Результаты в формате allure ожидаются в каталоге build/out/allure или его подкаталогах.
Инициализация:
- Информационная база инициализируется только в том случае, если в сборочной линии включены шаги, работающие с базой (например, bdd или syntaxCheck).
- Информационная база инициализируется конфигурацией из хранилища конфигурации (initInfobase -> initMethod).
- После загрузки конфигурации в ИБ будет выполняться запуск ИБ с целью запуска обработчиков обновления из БСП (initInfobase -> runMigration).
- Если в настройках шага инициализации не заполнен массив дополнительных шагов миграции (initInfobase -> additionalInitializationSteps), но в каталоге tools присутствуют файлы с именами, удовлетворяющими шаблону vrunner.init*.json, то автоматически выполняется запуск vrunner vanessa с передачей найденных файлов в качестве значения настроек (параметр --settings) в порядке лексиграфической сортировки имен файлов.
BDD:
- Если в конфигурационном файле проекта не заполнена настройка bdd -> vrunnerSteps, то автоматически выполняется запуск vrunner vanessa --settings tools/vrunner.json.
Синтаксический контроль:
- Если в репозитории существует файл 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).

13 KiB Raw Blame History