Клиентские модули 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
Как работать (роли)
Разработчик
- Вкладка «Модули» / модуль / «Создать ветку»:
feature/KTN-1234отdev. Или локально:git switch -c feature/KTN-1234 origin/dev. - Сделать задачу, открыть MR в
dev(в GitLab, галочка Squash commits). Pipeline проверит схему веток и соберёт модуль. - Замечания с теста /
bugfix/KTN-1234от актуальногоdev, снова MR.
Ревьюер / ведущий - Code Review MR в GitLab, затем на вкладке «Модули» «Влить / тест»: squash merge (одна задача = один коммит в dev), сборка dev уходит на тестовый сервер.
Аналитик / тестировщик - проверяет задачу на тесте.
Выпускающий
- «Релиз / стейдж»: версия X.Y.Z (по умолчанию +minor от прода) и галочки задач. Сайт создаёт
release/X.Y.Zотmainи MR в неё изrelease-prep/X.Y.Z. Если выбраны все задачи,release-prep- снимок текущей головыdev: задачи, влитые вdevво время Code Review, в релиз не попадут. Если галочка снята хоть с одной,release-prepсобирается отmaincherry-pick'ом только выбранных коммитов.devв обоих случаях не меняется. - MR вливается автоматически. Повтор или багфикс - «Влить / стейдж». В
release/X.Y.Zподнимается версия (<Version>в csproj) и пишется разделCHANGELOG.md, сборка уходит на стейдж, ставится тегvX.Y.Z-rc.N. - Баг на стейдже: мелкий -
bugfix/KTN-…отrelease/X.Y.Z/ MR в релиз / «Влить / стейдж». Критический - «Отменить релиз» и новый релиз после исправления вdev. - «Выпустить в прод»: MR
release / main/ pipeline / на прод выкладывается тот же артефакт, что проверен на стейдже / merge (если не удался - прод откатывается) / тегvX.Y.Z+ Release / обратное слияниеrelease / dev. - После smoke-check задаче в Kaiten - статус «Прод». Дошла ли версия до пользователей, видно в Grafana («Pilot - клиентские модули» / «Версии модулей на рабочих местах»).
Hotfix - «Создать hotfix-ветку от main» / исправление / MR в main (Code Review) / при желании «На стейдж (проверка)» / «Hotfix в прод». Сайт поднимет патч-версию, выложит на прод, поставит тег и вольёт hotfix в dev и в активный release/*. При конфликте MR синхронизации остаётся открытым. Ветка hotfix удаляется, только когда синхронизация прошла.
Откат прода - «Откатить прод на прошлый релиз»: на прод выкладывается сборка выбранного тега vX.Y.Z. Ветки не меняются; исправление потом выпускается hotfix'ом.
Что делает сайт при выкладке на сервер
- Берёт коммит (голова ветки или тег) и ждёт успешный pipeline этого коммита. Если pipeline нет, запускает его.
- Скачивает артефакты job
build_moduleи берёт из них zip модуля (bin/**/*.zip). Из главной сборки*.ext2.dllчитает имя, версию иAssemblyProduct, сборка при этом не загружается. - Находит модуль на сервере - объект
Extensionв папке расширений - по «Наименованию» (=AssemblyProduct), коду в скобках (… - (OpenStoradge) - (CICD)) или имени репозитория. - Пишет новую версию объекта: новый 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 и версию» на странице модуля. По ней вкладка «Модули» потом показывает, какой коммит на каком сервере. - Права (назначение пользователям) не меняются. Модуль, которого на сервере не было, создаётся никому не назначенным - назначьте его в 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.
Настройка, один раз:
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 пропущен или не удался..envадминки:MODULES_DEPLOY_KEY_TEST,MODULES_DEPLOY_KEY_STAGE,MODULES_DEPLOY_KEY_PRODи служебные учётки PilotMODULES_DEPLOY_{TEST,STAGE,PROD}_{LOGIN,PASSWORD}(пользователь базы с правами на папку расширений), затемdocker compose up -d.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: что изменилось
Подключение репозитория модуля
- Проект в группе модулей GitLab (настройка «Группа с клиентскими модулями», на этом стенде
http://localhost:8080/client-modules). Имя проекта - лучше код модуля из скобок (OpenStoradge). - В корне -
*.csprojмодуля сAssemblyNameNNNИмя.ext2, вAssemblyInfo.cs-AssemblyProduct("NN.NNN - Название - (Код) - (CICD)"),AssemblyCompany("CICD"); версия - только<Version>X.Y.Z</Version>в csproj (приGenerateAssemblyInfoвключена генерация одних атрибутов версии, см. Test-module). - Release-сборка должна собирать
bin/*.zip(targetCreateReleaseZip, как в Pilot.ClientSdk.csproj). Если zip нет, шаблон CI соберёт его из папки Release сам. - Вкладка «Модули» / модуль / «Подключить»: сайт создаст
devотmainи положит шаблон.gitlab-ci.ymlвdev. - Защитите ветки в 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. - Если модуль тянет пакеты из внутреннего 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.