GitLab CI/CD

Каноническая схема delivery-пайплайна проекта.

Платформа

SCM и CI/CD: GitLab.
Web-документация: GitLab Pages.
Release notes: GitLab Release + git-cliff.
Self-hosted runners: ci-build и ci-deploy на production-хосте.

Схема pipeline

graph LR
    subgraph verify["verify (MR + default + tag)"]
        ML[markdownlint]
        DG[docs-governance]
        DM[docs-mermaid]
        CV[compose-validate]
        BV[backend-verify]
        BT[backend-test]
        FV[frontend-verify]
        PL[plans-lint]
        RVV[release-verify-version<br/>tag only]
    end
    subgraph docs["docs (MR + default)"]
        DB[docs-build]
        P[pages<br/>default only]
    end
    subgraph deploy["deploy (default only)"]
        DP[deploy-production]
    end
    subgraph release["release (tag only)"]
        RN[release-notes]
        R[release]
    end

    CV --> DP
    DB --> DP
    RVV --> R
    RN --> R

Job	Стадия	Триггеры	Runner tag
`markdownlint`	verify	MR, default, tag, schedule	`ci-build`
`docs-governance`	verify	MR, default, tag, schedule	`ci-build`
`docs-mermaid`	verify	MR, default, tag, schedule	`ci-build`
`compose-validate`	verify	MR, default, tag, schedule	`ci-build`
`backend-verify`	verify	MR, default, tag, schedule	`ci-build`
`backend-test`	verify	MR, default, tag, schedule	`ci-build`
`frontend-verify`	verify	MR, default, tag, schedule	`ci-build`
`plans-lint`	verify	MR, default, tag, schedule	`ci-build`
`release-verify-version`	verify	tag only	`ci-build`
`docs-build`	docs	MR only	`ci-build`
`pages`	docs	default only	`ci-build`
`deploy-production`	deploy	default only	`ci-deploy`
`release-notes`	release	tag only	`ci-build`
`release`	release	tag only	`ci-build`

Стадии pipeline

verify
- markdown lint;
- проверка структуры docs;
- проверка docs-delta;
- проверка внутренних markdown ссылок;
- docker compose config для dev и production stack.
docs
- Quartz static build;
- публикация Pages из main.
deploy
- production deploy локально на host-mounted filesystem через ci-deploy;
- release материализуется как git worktree из персистентного bare-репо $DEPLOY_ROOT/repo.git в releases/<commit-sha>;
- подъем нового color-slot через docker compose up -d --build --remove-orphans;
- переключение active upstream snippet и nginx reload без downtime.
release
- валидация соответствия VERSION и git tag;
- генерация release notes;
- создание GitLab Release.

Триггеры

Merge Request pipeline

Обязателен для каждого MR. Должен блокировать merge при падении verify/docs jobs.

Pipeline на default-ветке

Повторяет verify/docs, публикует актуальный docs site в GitLab Pages и запускает production deploy.

Tag pipeline

Запускается на тегах vX.Y.Z, валидирует VERSION, собирает release notes и создаёт GitLab Release.

Scheduled pipeline

Используется для тяжёлых проверок:

sandbox smoke к поставщикам;
периодическая проверка docs/release toolchain;
расширенные интеграционные проверки.

Обязательные артефакты

public/ — сайт документации для Pages.
release-notes.md — release notes, сгенерированные pipeline.

Требования к runner’ам

ci-build должен иметь Docker socket для docker compose config и image build.
ci-deploy должен иметь Docker socket и host mounts /home/belkanov/apps, /etc/nginx.
Node.js runtime + git для Quartz build, Python runtime для docs scripts.
git и curl для production deploy job (release материализуется через git worktree).
Доступ к git history без shallow-limit для release jobs (GIT_DEPTH=0).

Обязательные CI/CD variables для deploy

DEPLOY_ROOT — корневой каталог релизов tracium на сервере, по умолчанию /home/belkanov/apps/tracium.
STATE_DIR — каталог runtime-state, по умолчанию /home/belkanov/apps/runtime-state.
APP_PROD_BASE_DOMAIN — production base domain (tracium.ru).
APP_PROD_DOCS_DOMAIN — docs domain (docs.tracium.ru).
APP_PROD_API_DOMAIN — API domain (api.tracium.ru).
DEPLOY_ENV_FILE в репозитории shared/auth — optional multiline env override для production auth stack. Если переменная не задана, deploy использует уже существующий host-side /home/belkanov/apps/shared-auth/shared/.env.

SSH-ключи для deploy больше не нужны: ci-deploy работает на самом production-хосте и пишет релизы напрямую в host-mounted каталог.

Актуальная topology production-хоста, ingress, runtime-state и systemd layout зафиксированы в:

../40-operations/production-environment.md

Blue/green lifecycle

ci-build валидирует compose, docs и image build.
ci-deploy вычисляет current/next color через runtime-state.
Новый release поднимается на loopback ports next-slot’а.
После health-check рендерится новый upstream snippet.
Host-side nginx проходит nginx -t и получает reload.
Только после успешного smoke-check обновляется файл *.active.

Правила merge

CI красный → merge запрещён.
Изменения вне docs без docs-delta → merge запрещён.
Release tag без совпадения с VERSION → release job падает.

Tracium

Разделы