diff --git a/.gitignore b/.gitignore index 1679da1..f6b65ad 100644 --- a/.gitignore +++ b/.gitignore @@ -9,7 +9,7 @@ [Oo]ut bdd-*.xml -[Cc]overage/* +[Cc]overage *.log *.ospx diff --git a/README.md b/README.md index 62d50b2..f5433c5 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,34 @@ + # vanessa-ci-scripts -Набор скриптов Continuous Integration for 1C. Устанавливается как приложение OScript на компьютер с ролью GitLab-runner. -Предназначена для быстрого перехода к использованию GitLab pipeline. +- [vanessa-ci-scripts](#vanessa-ci-scripts) + - [Введение](#введение) + - [Файловая структура](#файловая-структура) + - [Установка](#установка) + - [Использование](#использование) + - [Взаимосвязи заданий](#взаимосвязи-заданий) + - [Шаг ".pre"](#шаг-pre) + - [Шаг "deploy" для вашего проекта](#шаг-deploy-для-вашего-проекта) + - [Настройка](#настройка) + - [Выполнение](#выполнение) + - [Доступные команды](#доступные-команды) + - [Глобальные переменные окружения](#глобальные-переменные-окружения) + - [Возможности доработки](#возможности-доработки) + - [Публикация релиза](#публикация-релиза) + - [Включение отладки](#включение-отладки) + - [Благодарность](#благодарность) + +## Введение + +Набор скриптов Continuous Integration for 1C. Устанавливается как приложение OScript на компьютер с ролью Gitlab-runner. +Предназначена для быстрого перехода к использованию Gitlab pipeline. Все требуемые библиотеки и приложения уже есть внутри VCI, по этому для работы pipeline достаточно выполнить установку приложения, чтобы gitsync, vanessa runner etc. выполнялись на runner. -parent: -![preview-pipeline1](./doc/image/preview-pipeline1.png "preview-pipeline1") -child: -![preview-pipeline2](./doc/image/preview-pipeline2.png "preview-pipeline2") - -## Использование +**parent**: +![preview-pipeline-parent](./doc/image/preview-pipeline-parent.jpg "preview-pipeline-parent") +**child**: +![preview-pipeline-child](./doc/image/preview-pipeline-child.jpg "preview-pipeline-child") Проект опирается на структуру каталогов и файлов настроек из проектов: @@ -20,9 +38,60 @@ child: **Важно! Если ваш проект отличается от описанных шаблонов, то pipeline выполнится с ошибками.** -В каталоге [```example\test-vci.zip```](./example/test-vci.zip) хранится пример пустого проекта, в котором можно посмотреть структуру и файлы настроек которые требуются для работы ```vanessa-ci-scripts``` +### Файловая структура + +```shell +├── .vscode/ # Полезные команды и настройки для VSC + ├── settings.json + ├── tasks.json +├── build/ # * Каталог с артефактами + ├── allure-report/ # Сгенерированный отчет allure framework + ├── cfe/ + ├── epf/ + ├── erf/ + ├── ib/ + ├── 1Cv8.cf +├── coverage/ # * Каталог с результатами замеров покрытия кода +├── doc/ # Документация +├── examples/ # Примеры тестов, скриптов или обработок +├── features/ # Сценарии BDD тестирования +├── fixtures/ # Основные зависимости +├── lib/ # Для хранения внешних отчетов и обработок необходимых для работы продукта, разработанные в рамках создания продукта и не являющиеся сторонними разработками +├── out/ # * Каталог с артефактами выполнения тестов +├── public/ # * Каталог для работы GitLab pages +├── src/ # Исходный код проекта + ├── cf/ # Код из конфигурации + ├── cfe/ # Код из расширений + ├── <имя расширения> # + ├── epf/ # Внешние обработки + ├── erf/ # Внешние отчеты +├── tasks/ # Основные таски (opm run <имя-скрипта>) +├── template/ # Эталонные файлы + ├── 1Cv8.dt # Выгрузка эталонной ИБ для тестов +├── tests/ # Модульные тесты (TDD) +└── tools/ # + ├── JSON/ # Файлы настроек для runner'ов etc + ├── vanessabddConf.json # Настройки vanessa add (BDD, vanessa) + ├── vanessatddConf.json # Настройки vanessa add (TDD, xunit) + ├── vaparams.json # Настройки vanessa automation (BDD, vanessa) + ├── scripts/ # Служебные и пользовательские скрипты + ├── install-oscript-local.bat # Скрипт установки OScript + └── syntax-check-excludes.txt # Настройки исключений для синтаксического контроля +├── vendor/ # Для хранения внешних зависимостей - библиотек, конфигураций etc +├── .gitlab-ci.yml # Конфигурационный файл для gitlab pipeline +├── cliff.toml # Настройки формирование CHANGELOG с помощью git-cliff +├── env.json # Параметры окружения для локальной/эталонной ИБ (только для прохождения pipeline) +├── env.prod.json # ** Параметры окружения production ИБ (Используются для шага Deploy) +├── env.dev1.json # ** Параметры окружения dev1 ИБ (Используются для шага Deploy) +├── env.user-testin.json # ** Параметры окружения user-testing ИБ (Используются для шага Deploy) +├── sonar-project.properties # Параметры работы SonarQube +└── README.md # Описание репозитория +``` + +`*` - Создается в процессе работы pipeline +`**` - Может быть неограниченное количество. [Смотрите пункт Deploy](#шаг-deploy-для-вашего-проекта) -### Порядок установки +### Установка Из hub.oscript: @@ -30,20 +99,16 @@ child: opm install vanessa-ci-scripts ``` -Скачайте и установите приложение через hub.oscript с помощью скрипта: - -- [```tools\scripts\install-package-from-hub.bat```](./tools/scripts/install-package-from-hub.bat) - -Или собрав и установив приложение из пакета в формате ```.*ospx``` с помощью скриптов: +Или собрав и установив приложение из пакета в формате `.*ospx` с помощью команд: -- [```tools\scripts\build-package.bat```](./tools/scripts/build-package.bat) -- [```tools\scripts\install-package-from-ospx.bat```](./tools/scripts/install-package-from-ospx.bat) - -### Порядок использования +```Shell +opm run build +opm run install +``` - +### Использование -Чтобы начать работу, нужно клонировать ваш удаленный репозиторий с сервера ```https://gitlab.com/```. +Чтобы начать работу, нужно клонировать ваш удаленный репозиторий с сервера `https://gitlab.com/`. Открыть командную строку в проекте. Выполните команду инициализации: @@ -51,16 +116,116 @@ opm install vanessa-ci-scripts vci init ``` -В корне проекта будет создан файл ```.gitlab-ci.yml``` и ```tools\scripts\install-oscript-local.bat``` +В корне проекта будет создан файл `.gitlab-ci.yml` и `tools\scripts\install-oscript-local.bat` Отправьте изменения в удаленный репозиторий, чтобы запустить pipeline ```Shell git add .gitlab-ci.yml git add tools\\scripts\\install-oscript-local.bat -git commit -m "ci(!): #нетзадачи - Инициализировал файл настроек pipeline" +git commit -m "ci(vci): Инициализированы файлы настроек pipeline" +git push ``` +Настройте график выполнения синхронизации с хранилищем +В веб интерфейсе репозитория перейдите в "Build" - "Pipeline schedules" и создайте новое расписание + +![edit-pipeline-schedule](./doc/image/edit-pipeline-schedule.jpg "edit-pipeline-schedule") + +Запустите Pipeline +В веб интерфейсе репозитория перейдите в "Build" - "Pipeline" и нажмите "Run pipeline" +В открывшемся окне выберите branch или tag для запуска и нажмите "Run pipeline" + +### Взаимосвязи заданий + +**parent**: +![needs-pipeline-parent](./doc/image/needs-pipeline-parent.jpg "needs-pipeline-parent") +**child**: +![needs-pipeline-child](./doc/image/needs-pipeline-child.jpg "needs-pipeline-child") + +#### Шаг ".pre" + +Перед началом работы вашего pipeline требуется установить на runner только [git-scm.com](https://git-scm.com/downloads) +Для упрощения, в файл `.gitlab-ci.yml` включен шаг `.pre`, выполните его последовательно и ваш gitlab runner будет готов к работе. + +**Важно! Некоторые программы из шага требуют перезапуска службы gitlab-runner, поэтому, если шаг `install-chocolatey` выполнился успешно, а подчиненные шаги сообщают об ошибке, то перезапустите службы.** + +**Важно2! Служба gitlab-runner должна исполняться из под пользователя Windows (То есть не системная учетная запись).** + +### Шаг "deploy" для вашего проекта + +Отдельно стоит упомянуть о такой части жизненного цикла как `Deploy`. +Это размещение готовой версии программного обеспечения на платформе доступной для использования. + +#### Настройка + +Скачайте в корень вашего проекта файлы с переменными окружения (может быть несколько) + +```Shell +cd <каталог-вашего-проекта> +curl -o env.production.json -O https://raw.githubusercontent.com/vanessa-opensource/vanessa-bootstrap/master/env.json +``` + +Переключите переменные окружения на использование Vanessa-automation + +```Shell +vci run switch-vanessa "env.production.json" +``` + +Имена файлов с переменными окружения должны быть составлены по шаблону `env.*.json`, где `*` - имя окружения (понятное Вам и коллегам), например: + +- `env.production.json` +- `env.user-test.json` +- `env.dev.json` + +Измените значения переменных окружения в соответствии с настройками ваших серверов и ИБ, блок `default` + +```JSON +{ + "$schema": "https://raw.githubusercontent.com/vanessa-opensource/vanessa-runner/develop/vanessa-runner-schema.json", + "default": { + "--ibconnection": "/Fbuild/ib", + "--db-user": "", + "--db-pwd": "", + "--root": ".", + "--workspace": ".", + "--v8version": "8.3.16", + "--locale": "ru", + "--language": "ru", + "--additional": "/DisplayAllFunctions /Lru /iTaxi /TESTMANAGER", + "--ordinaryapp": "-1" + } +} +``` + +Отправьте изменения в удаленный репозиторий + +```Shell +git add env.production.json +git commit -m "ci(vci): Инициализироваы файлы окружения" +git push +``` + +Установите компоненту RAS на серверах 1С и зарегистрируйте как службу ([Ссылка на инструкцию по установки](https://its.1c.ru/db/freshex2/content/509/hdoc)) +Установите компоненту RAC на зарегистрированные gitlab runner + +#### Выполнение + +В веб интерфейсе репозитория перейдите в "Build" - "Pipeline" и нажмите "Run pipeline" +В открывшемся окне: + +- выберите branch, который указан по умолчанию для вашего репозитория +- добавьте переменную с типом "variable", именем "deploy" и значением 1 +- нажмите "Run pipeline" + +![run-pipeline-deploy-variable](./doc/image/run-pipeline-deploy-variable.jpg "run-pipeline-deploy-variable") + +Создастся pipeline с шагами deploy* по количеству файлов переменных окружения в репозитории вашего проекта + +![execute-pipeline-deploy-env](./doc/image/execute-pipeline-deploy-env.jpg "execute-pipeline-deploy-env") + +Выполните его последовательно контролируя результат + ### Доступные команды Генерация pipeline: @@ -69,7 +234,7 @@ git commit -m "ci(!): #нетзадачи - Инициализировал фа vci generate ``` -Подготовка окружения (Скачать ovm, установка локального oscript и библиотек, TODO не имеет сейчас смысла): +**[DEPRECATED]** Подготовка окружения (Скачать ovm, установка локального oscript и библиотек): ```Shell vci prepare @@ -83,8 +248,8 @@ vci run Доступные имена скриптов: - -- ```test``` - проверить работоспособность (hello world); + +- ```hello-world``` - проверить работоспособность; - ```create-base``` - создать служебную ИБ из шаблона (```template\1Cv8.dt```) и обновить актуальными исходниками (```src\cf```) в служебном каталоге (```build\ib```); - ```open``` - открыть клиент предприятия; - ```designer``` - открыть конфигуратор; @@ -110,7 +275,7 @@ vci run | Имя | Описание | |----------------------------|------------------------------------------------------------------------------------------------------------------------------| -| `GROUP_ACCESS_TOKEN` | токен с правами "read_repository, write_repository", для использования [gitsync](https://github.com/oscript-library/gitsync) | +| `VCI_GROUP_ACCESS_TOKEN` | токен с правами "read_repository, write_repository", для использования [gitsync](https://github.com/oscript-library/gitsync) | | `OVM_INSTALL_VERSION` | устанавливаемая версия OScript | | `OVM_USE_VERSION` | используемая версия OScript | | `GITSYNC_V8VERSION` | версия 1С Предприятия (Например 8.3.23.1782) | @@ -119,15 +284,17 @@ vci run | `GITSYNC_STORAGE_PASSWORD` | пароль к хранилищу 1С для синхронизации с git (Например ci-bot) | | `GITSYNC_WORKDIR` | рабочий каталог в git репозитории для выгрузки исходников конфигурации (Например "./src/cf/") | | `GITSYNC_VERBOSE` | вывод отладочной информации в процессе выполнения | -| `UCCODE` | код разрешения для входа в 1С | | `SONAR_HOST_URL` | хост SonarQube | | `SONAR_TOKEN` | токен доступа к проекту SonarQube | +| `VCI_UCCODE` | код разрешения для входа в 1С | +| `VCI_CLUSTER_ADMIN` | администратор кластера 1С | +| `VCI_CLUSTER_PWD` | пароль администратора кластера 1С | | `VCI_VERBOSE` | вывод отладочной информации в процессе выполнения | ## Возможности доработки - откройте issue - если вам не хватает какого то функционала для вашего pipeline -- войдите в чат Телеграм - чтобы задать дополнительные вопросы [![telegram](https://img.shields.io/badge/telegram-chat-green.svg)](https://t.me/oscript_library) +- войдите в чат Телеграм - чтобы задать дополнительные вопросы [![Telegram](https://img.shields.io/badge/telegram-chat-green.svg)](https://t.me/oscript_library) - сделайте fork, внесите изменения и выполните pull request с предлагаемыми вами изменениями (fork и pull request - это кнопки на GitHub|GitLab.) ## Публикация релиза @@ -145,6 +312,6 @@ vci run ## Благодарность - Opensource сообществу 1C и OneScript -- [Сергею Голованову](https://t.me/GolovanoffSergio) за презентацию на "Infostart Event 2023" +- [Сергею Голованову](https://t.me/GolovanoffSergio) за доклад на "Infostart Event 2023" с темой "Эволюция нашего Gitlab CI человекообразный плейстоцен" - [Никите Федькину](https://t.me/nixel2007) за ответы на вопросы - Всем кто отвечал на мои вопросы diff --git a/doc/image/edit-pipeline-schedule.jpg b/doc/image/edit-pipeline-schedule.jpg new file mode 100644 index 0000000..3208c2e Binary files /dev/null and b/doc/image/edit-pipeline-schedule.jpg differ diff --git a/doc/image/execute-pipeline-deploy-env.jpg b/doc/image/execute-pipeline-deploy-env.jpg new file mode 100644 index 0000000..78d0736 Binary files /dev/null and b/doc/image/execute-pipeline-deploy-env.jpg differ diff --git a/doc/image/needs-pipeline-child.jpg b/doc/image/needs-pipeline-child.jpg new file mode 100644 index 0000000..cbd197e Binary files /dev/null and b/doc/image/needs-pipeline-child.jpg differ diff --git a/doc/image/needs-pipeline-parent.jpg b/doc/image/needs-pipeline-parent.jpg new file mode 100644 index 0000000..00d7191 Binary files /dev/null and b/doc/image/needs-pipeline-parent.jpg differ diff --git a/doc/image/preview-pipeline-child.jpg b/doc/image/preview-pipeline-child.jpg new file mode 100644 index 0000000..6ea9da8 Binary files /dev/null and b/doc/image/preview-pipeline-child.jpg differ diff --git a/doc/image/preview-pipeline-parent.jpg b/doc/image/preview-pipeline-parent.jpg new file mode 100644 index 0000000..1832bea Binary files /dev/null and b/doc/image/preview-pipeline-parent.jpg differ diff --git a/doc/image/preview-pipeline1.png b/doc/image/preview-pipeline1.png deleted file mode 100644 index 527331c..0000000 Binary files a/doc/image/preview-pipeline1.png and /dev/null differ diff --git a/doc/image/preview-pipeline2.png b/doc/image/preview-pipeline2.png deleted file mode 100644 index c348c00..0000000 Binary files a/doc/image/preview-pipeline2.png and /dev/null differ diff --git a/doc/image/run-pipeline-deploy-variable.jpg b/doc/image/run-pipeline-deploy-variable.jpg new file mode 100644 index 0000000..109a1aa Binary files /dev/null and b/doc/image/run-pipeline-deploy-variable.jpg differ diff --git a/example/test-vci.zip b/example/test-vci.zip deleted file mode 100644 index 7f7ff8a..0000000 Binary files a/example/test-vci.zip and /dev/null differ