ADR-0022: GitLab CI/CD, docs-as-code и управление релизами
Status: accepted Date: 2026-04-17 Deciders: команда проекта
Контекст
Проекту нужен единый delivery-контур и формализованная web-доступная документация. До фиксации решения отсутствовали:
- канонический CI/CD platform choice;
- обязательный web-путь публикации документации;
- единое правило версионирования и changelog;
- автоматический release flow.
Решение
Фиксируются следующие правила:
- GitLab — каноническая платформа для CI/CD.
- Quartz — сборка документации из
docs/docs/. - GitLab Pages — web-публикация актуальной документации из
main. - SemVer — схема версионирования продукта.
- Keep a Changelog — формат
CHANGELOG.md. - Conventional Commits — базовый commit taxonomy для релизной автоматизации.
- git-cliff — генерация release notes в GitLab pipeline.
Pipeline обязан покрывать:
- markdown lint;
- проверку структуры документации и внутренних ссылок;
docker compose config;- Quartz static build;
- публикацию GitLab Pages;
- release jobs по version tags
vX.Y.Z.
Любое изменение поведения, контракта, deploy, CI/CD или процесса должно менять документацию в том же MR.
Последствия
Плюсы
- Документация доступна в web без отдельного ручного шага.
- Delivery-процесс формализован и проверяем CI.
- Версия продукта и история изменений появляются с первого дня.
- Изменения в архитектуре, операционке и процессах перестают “жить в чате”.
Минусы
- Появляется обязательный overhead на поддержку docs и changelog.
- Любые изменения, даже инфраструктурные, требуют дисциплины обновления документации.
Нейтральные последствия
- Документы остаются canonical markdown в репозитории; GitLab Pages только проекция этих файлов.
Рассмотренные альтернативы
Документация только в репозитории без web-публикации
Отклонено: не выполняет требование читабельности через web.
Отдельный docs-портал вне GitLab
Отклонено: лишний operational overhead и раздвоение источника истины.
Release notes вручную
Отклонено: ручной процесс плохо масштабируется и быстро расходится с коммитами.