Клиентские модули Pilot: CI/CD

Как клиентский модуль проходит путь от задачи в Kaiten до прода. Три контура, три вида веток:

Ветка Сервер Pilot Что там
feature/KTN-1234, bugfix/KTN-1234 - задача; от dev, в dev через MR со squash
dev тест (:5547) всё проверенное Code Review; выкладывается после каждого влития задачи
release/X.Y.Z (+ теги vX.Y.Z-rc.N) стейдж (:5549) состав релиза зафиксирован; только мелкие багфиксы
main (+ теги vX.Y.Z) прод (:5546) стабильные релизы
hotfix/KTN-1234 стейдж (проверка) / прод срочный баг прода; от main, потом в dev и активный release

Что где лежит:

Папка Что это
Pilot.ClientSdk/ клиентский модуль 113Pilot.ClientSdk.ext2 (NuGet-пакет Pilot.ClientSdk; до 2.0.0 - Modules): статистика модулей в Grafana + общие методы SDK
ci-template/.gitlab-ci.yml шаблон CI для репозитория модуля: схема веток в MR, проверка версии и CHANGELOG, сборка zip, проверка библиотек, выкладка dev/release/main (тег vX.Y.Z и GitLab Release ставит веб-админка при выпуске в прод)
Test-module/ тестовый модуль 114TestModule.ext2 для проверки CI/CD и ошибок в Grafana
../proadmin веб-админка, вкладка «Модули»: все операции CI/CD, запись модулей на серверы
../stack/metrics/report-collector сервис статистики: POST /api/module-events / metrics.module_events, дашборд «Pilot - клиентские модули»
                 Code Review (GitLab)            Code Review (GitLab)
feature/KTN-… ──MR, squash──dev ──снимок (все задачи)──────┐
                               │   или cherry-pick выбранных     ├─release-prep/X.Y.Z ──MR──release/X.Y.Z ──MR──main ──тег vX.Y.Z
                               │   от main ───────────────────────┘                                  │                  │

                         сервер ТЕСТ                          сервер СТЕЙДЖ          сервер ПРОД
                  (zip из CI сборки dev)                (zip из CI, тег rc)   (тот же zip, что на стейдже)
                                                                                        │
                                              release/X.Y.Z ──обратное слияние──dev ◄─┘
hotfix/KTN-… (от main) ──MR──main ──прод, тег vX.Y.(Z+1) ──hotfix / dev и / активный release

Как работать (роли)

Разработчик

  1. Вкладка «Модули» / модуль / «Создать ветку»: feature/KTN-1234 от dev. Или локально: git switch -c feature/KTN-1234 origin/dev.
  2. Сделать задачу, открыть MR в dev (в GitLab, галочка Squash commits). Pipeline проверит схему веток и соберёт модуль.
  3. Замечания с теста / bugfix/KTN-1234 от актуального dev, снова MR.

Ревьюер / ведущий - Code Review MR в GitLab, затем на вкладке «Модули» «Влить / тест»: squash merge (одна задача = один коммит в dev), сборка dev уходит на тестовый сервер.

Аналитик / тестировщик - проверяет задачу на тесте.

Выпускающий

  1. «Релиз / стейдж»: версия X.Y.Z (по умолчанию +minor от прода) и галочки задач. Сайт создаёт release/X.Y.Z от main и MR в неё из release-prep/X.Y.Z. Если выбраны все задачи, release-prep - снимок текущей головы dev: задачи, влитые в dev во время Code Review, в релиз не попадут. Если галочка снята хоть с одной, release-prep собирается от main cherry-pick'ом только выбранных коммитов. dev в обоих случаях не меняется.
  2. MR вливается автоматически. Повтор или багфикс - «Влить / стейдж». В release/X.Y.Z поднимается версия (<Version> в csproj) и пишется раздел CHANGELOG.md, сборка уходит на стейдж, ставится тег vX.Y.Z-rc.N.
  3. Баг на стейдже: мелкий - bugfix/KTN-… от release/X.Y.Z / MR в релиз / «Влить / стейдж». Критический - «Отменить релиз» и новый релиз после исправления в dev.
  4. «Выпустить в прод»: MR release / main / pipeline / на прод выкладывается тот же артефакт, что проверен на стейдже / merge (если не удался - прод откатывается) / тег vX.Y.Z + Release / обратное слияние release / dev.
  5. После smoke-check задаче в Kaiten - статус «Прод». Дошла ли версия до пользователей, видно в Grafana («Pilot - клиентские модули» / «Версии модулей на рабочих местах»).

Hotfix - «Создать hotfix-ветку от main» / исправление / MR в main (Code Review) / при желании «На стейдж (проверка)» / «Hotfix в прод». Сайт поднимет патч-версию, выложит на прод, поставит тег и вольёт hotfix в dev и в активный release/*. При конфликте MR синхронизации остаётся открытым. Ветка hotfix удаляется, только когда синхронизация прошла.

Откат прода - «Откатить прод на прошлый релиз»: на прод выкладывается сборка выбранного тега vX.Y.Z. Ветки не меняются; исправление потом выпускается hotfix'ом.

Что делает сайт при выкладке на сервер

  1. Берёт коммит (голова ветки или тег) и ждёт успешный pipeline этого коммита. Если pipeline нет, запускает его.
  2. Скачивает артефакты job build_module и берёт из них zip модуля (bin/**/*.zip). Из главной сборки *.ext2.dll читает имя, версию и AssemblyProduct, сборка при этом не загружается.
  3. Находит модуль на сервере - объект Extension в папке расширений - по «Наименованию» (= AssemblyProduct), коду в скобках (… - (OpenStoradge) - (CICD)) или имени репозитория.
  4. Пишет новую версию объекта: новый zip (старый уходит в историю версий), атрибуты «Наименование» и «Версия X.Y.Z - Размер …». Причина версии - X.Y.Z · ветка @ коммит - задачи. Версия модуля - три числа X.Y.Z и только в <Version> csproj (<Version>1.4.0</Version>; в AssemblyInfo.cs и <FileVersion> версии нет, AssemblyVersion/FileVersion генерирует SDK). Руками версию не поднимаем: её выставляет «Релиз / стейдж» (minor) или «Hotfix» (patch); в MR задачи check_version предупредит, если версию поменяли. Шаблон CI и перевод версии в одно место - кнопка «Обновить CI и версию» на странице модуля. По ней вкладка «Модули» потом показывает, какой коммит на каком сервере.
  5. Права (назначение пользователям) не меняются. Модуль, которого на сервере не было, создаётся никому не назначенным - назначьте его в Pilot-myAdmin.

Все операции идут в фоне, журнал с ссылками на MR, pipeline и job - вкладка «Операции».

Автоматическая выкладка из GitLab CI

Слияние, сделанное прямо в GitLab, выкладывается без кнопок админки - это делает pipeline шаблона ci-template/.gitlab-ci.yml:

Ветка Job Куда
любой MR, любая ветка check_version MR задачи (в dev, release/*): предупреждение (job жёлтый, pipeline идёт дальше), если версию поменяли вручную, - её выставляет «Релиз / стейдж» или «Hotfix». main/master: версия выросла относительно состояния ветки до слияния, тег vX.Y.Z не стоит на другом коммите, в CHANGELOG.md есть раздел ## [X.Y.Z]; иначе ошибка. Остальные ветки: проверяется только, что версия определяется
любая build_module zip модуля. В ветке dev к версии дописывается номер сборки (1.3.0 / 1.3.0.4: сколько задач в dev сверх тега релиза), по нему видно, обновился ли модуль на тесте
любая check_libraries состав zip и ссылки сборки сверяются с правилами «Библиотеки модулей» в админке. Нарушение в запрещающем режиме - ошибка, выкладка запрещена; в режиме предупреждений job жёлтый
dev deploy_test сервер тест
release/* deploy_stage сервер стейдж
main / master deploy_prod сервер прод. Тег vX.Y.Z и GitLab Release (описание - раздел CHANGELOG.md) ставит веб-админка при выпуске в прод, задания release в CI нет

deploy_* отправляет zip в админку (POST /api/ci/modules/deploy) с двумя доказательствами: заголовок X-Deploy-Key - ключ своего контура (deploy_test - тест, deploy_stage - стейдж, deploy_prod - прод), заголовок X-Job-Token - токен задания CI_JOB_TOKEN. Админка проверяет токен в GitLab (GET /api/v4/job) и берёт оттуда ветку, коммит, проект и pipeline; контур определяется по проверенной ветке (dev / тест, release/* / стейдж, main/master / прод). Поля формы ref, sha, project, user, pipeline_url нужны только для диагностики: если они не совпадают с проверенными, админка ответит 400. Проект должен лежать в группе клиентских модулей из настроек админки, иначе 403. Админка пишет zip на сервер контура так же, как кнопка «Выложить» (новая версия объекта Extension, причина версия · ветка @ коммит - заголовок коммита) и печатает свой журнал в лог job. Операция видна и во вкладке «Операции». check_libraries ничего не выкладывает, ему достаточно X-Job-Token.

Настройка, один раз:

  1. GitLab / группа модулей / Settings / CI/CD / Variables, по ключу на контур (значения - MODULES_DEPLOY_KEY_TEST, MODULES_DEPLOY_KEY_STAGE, MODULES_DEPLOY_KEY_PROD из .env админки):

    • DEPLOY_KEY_TEST - Masked;
    • DEPLOY_KEY_STAGE - Masked и Protected;
    • DEPLOY_KEY_PROD - Masked и Protected.

    Protected-переменная доступна только заданиям на защищённых ветках (main, release/*), поэтому разработчик не прочитает ключ стейджа и прода из своей ветки. Флаг Protect у этих двух переменных не снимайте. Если админка не на этом же Docker-хосте - ещё ADMIN_URL, лучше https://…: по HTTP ключи и zip идут открытым текстом. Как выпустить ключи и в какие группы их класть - server-extensions/README.md. Установщик стека на машине с ролью gitlab задаёт эти переменные в группах модулей сам (значения из .env, старую DEPLOY_KEY удаляет); вручную - если его шаг GitLab пропущен или не удался.

  2. .env админки: MODULES_DEPLOY_KEY_TEST, MODULES_DEPLOY_KEY_STAGE, MODULES_DEPLOY_KEY_PROD и служебные учётки Pilot MODULES_DEPLOY_{TEST,STAGE,PROD}_{LOGIN,PASSWORD} (пользователь базы с правами на папку расширений), затем docker compose up -d.

  3. Runner: Docker-executor с доступом к админке (host.docker.internal:5300). Локальный runner - ../gitlab, сеть заданий gitlab_gitlab-net.

Переход со старой схемы: общая переменная DEPLOY_KEY (MODULES_DEPLOY_KEY) больше не нужна. Админка принимает её только для контура тест и только пока MODULES_DEPLOY_KEY_TEST не задан; на стейдж и прод она не действует. Удалите её из группы после создания трёх новых. Шаблон .gitlab-ci.yml в репозиториях модулей обновите кнопкой «Обновить CI и версию»: старый шаблон шлёт DEPLOY_KEY без X-Job-Token, и админка его отвергнет.

CHANGELOG.md в репозитории модуля:

## [1.1.0] - 2026-10-05

- KTN-123: что изменилось

Подключение репозитория модуля

  1. Проект в группе модулей GitLab (настройка «Группа с клиентскими модулями», на этом стенде http://localhost:8080/client-modules). Имя проекта - лучше код модуля из скобок (OpenStoradge).
  2. В корне - *.csproj модуля с AssemblyName NNNИмя.ext2, в AssemblyInfo.cs - AssemblyProduct("NN.NNN - Название - (Код) - (CICD)"), AssemblyCompany("CICD"); версия - только <Version>X.Y.Z</Version> в csproj (при GenerateAssemblyInfo включена генерация одних атрибутов версии, см. Test-module).
  3. Release-сборка должна собирать bin/*.zip (target CreateReleaseZip, как в Pilot.ClientSdk.csproj). Если zip нет, шаблон CI соберёт его из папки Release сам.
  4. Вкладка «Модули» / модуль / «Подключить»: сайт создаст dev от main и положит шаблон .gitlab-ci.yml в dev.
  5. Защитите ветки в GitLab (Settings / Repository / Protected branches): main - Allowed to push: No one, release/* - Allowed to push: Maintainers (сайт создаёт release/X.Y.Z и коммитит в неё версию и CHANGELOG.md, при No one эти коммиты отклонятся), у обеих Allowed to merge: Maintainers; dev - push и merge - Maintainer (при подключении сайт от имени выпускающего коммитит .gitlab-ci.yml в dev). Установщик стека ставит эту защиту сам на машине с ролью gitlab: main и master - push No one, merge Maintainers, release/* и dev - push и merge Maintainers. Защита main и release/* обязательна: на ней держатся Protected-ключи стейджа и прода (см. «Настройка, один раз»). В Merge requests включите Squash commits when merging: Encourage и Pipelines must succeed - синхронизирующие MR (release / dev, hotfix / dev) сайт тогда ставит на автослияние после pipeline. «Pipelines must succeed» оценивается по .gitlab-ci.yml из ветки MR, который автор MR вправе менять, поэтому реальный барьер перед main - ревью Maintainer.
  6. Если модуль тянет пакеты из внутреннего NuGet (Pilot.ClientSdk), положите в репозиторий nuget.config из Test-module и подставьте в нём адрес вашего GitLab и id проекта Pilot.ClientSdk (в образце - gitlab.example.local и PROJECT_ID). CI входит в источник сам (токен job, шаг в build_module), но только если хост в адресе источника совпадает с хостом этого GitLab (CI_SERVER_HOST, без порта): источнику на другом хосте токен не отдаётся, и его пакеты не восстановятся, поэтому пишите в nuget.config то же имя, по которому GitLab видит сам себя. Разработчику один раз нужно подключить источник GitLab на своей машине и войти логином GitLab и личным токеном - пошагово в README Pilot.ClientSdk, 4.2.

Настройки веб-админки (страница «Настройки»)

Поле Значение
Серверы Pilot / Стейдж http://localhost:5549/pilot-ice_ru (только для модулей)
Группа с клиентскими модулями http://localhost:8080/client-modules. Выкладка из CI принимает только проекты из этой группы (иначе 403)
Job сборки модуля в CI build_module
Номер задачи (regex) KTN-\d+
Ссылка на задачу Kaiten https://<компания>.kaiten.ru/space/<id>/card/{number} (необязательно)

Pilot: на каждом сервере нужен пользователь базы с правами на папку расширений. Если учётка входа не подходит, вкладка «Модули» спросит логин и пароль отдельно для сервера.

Статистика и Grafana

Сервис report-metrics-collector принимает события модулей на POST /api/module-events и пишет их в pilot_metrics.metrics.module_events. Таблица создаётся сама при старте сервиса. Дашборд «Pilot - клиентские модули» подключается сам, в папке «CI/CD Pilot». Сводка без Grafana: GET http://<хост>:5310/api/module-events/summary?hours=24.