Всё есть код, или зачем внедрять GitOps в разработку

Привет, Хабр! Сегодня мы часто говорим про разные тренды в разработке — ИИ-агентов, тестирование на ранних стадиях, прослеживаемость изменений, автоматизацию пайплайнов… Все эти тренды звучат убедительно, пока не упираются в реальность: требования лежат в на общих дисках, схемы — в картинках, контракты — в разных версиях, а история изменений размазана по инструментам.
Что делать с этим?
Лев Немировский, руководитель направления по развитию инструментов внедрения ПСБ, рассказал, чем полезен в этом случае подход GitOps и о том, как и в каких случаях это может упростить жизнь команде.
Это не полный список трендов, о которых повсеместно говорят на ИТ-конференциях и вообще в ИТ-сообществе. Но для сегодняшней темы мы рассмотрим такие практики:

Все эти практики упираются в качество артефактов. Для работы ИИ нужны машиночитаемые артефакты. Для безопасности — полная прослеживаемость всех изменений. Для подхода Shift-left Testing — возможность перенести тестирование на этап аналитики и проектирования. А для скорости — качественная автоматизация всего пайплайна.
На практике с этим возникают проблемы. Например, ИИ-агент может открыть страницу на внутреннем портале, но такую проверку сложно сделать воспроизводимой: нет стабильного формата, понятного diff, версии и места, где проверка должна упасть автоматически. Мы не всегда можем отследить, кто, когда и зачем изменил тот или иной артефакт. Требования порой формулируются постфактум, уже после разработки. Даже при автоматизации и CI/CD находятся причины для ручных правок на проде в пятницу вечером.
И вот здесь на помощь приходит GitOps. В классическом смысле GitOps — это подход к управлению инфраструктурой и деплоем, где Git становится единственным источником истины. Но сам принцип шире: если артефакт можно описать как код, его можно проверять, версионировать, ревьюить и публиковать через пайплайн. Он позволяет нам хранить и версифицировать всё это:
 

• машиночитаемые форматы (YAML, OpenAPI, Markdown, JSON);
  
• полную историю изменений (кто, когда, что и зачем сделал);
  
• валидацию на этапе коммита (shift-left);
  
• автоматические пайплайны (CI/CD для всего).

Главная идея GitOps проста: всё, что влияет на систему, должно жить как код.
С помощью Git мы можем автоматизировать практически всё и привести в нужное состояние наши артефакты.
Какие артефакты можно хранить в Git?

• API-контракты (OpenAPI/AsyncAPI);
  
• модели данных (ER-диаграммы в формате DBML, PlantML;
  
• сценарии интеграции (sequence diagrams, BPMN);
  
• бизнес-правила (в формате YAML/Markdown);
  
• текстовую документацию;
  
• архитектуру.

Мы привыкли, что обычно разработка автоматизирована — лучше или хуже, но хотя бы с точки зрения самого кода. Однако тот пласт, который готовят аналитики (где-то — бизнес-аналитики, где-то — системные аналитики, где-то — тестирование совместно с разработкой), — он обычно за гранью автоматизации. 
Это не ломает привычный цикл разработки, но добавляет к нему проверяемость: требования, контракты и схемы проходят тот же путь, что и код. То есть все этапы останутся: мы будем планировать, выяснять и выявлять требования. Но мы их будем описывать как код, а затем собирать из них артефакты, проводить тестирование, релизить. У нас по-прежнему будет версионирование, деплой (в прод или во внутреннюю систему), а также этап эксплуатации системы.

Давайте я покажу несколько кейсов, как можно применить подход GitOps.
Контракты как код 
Это, пожалуй, самый очевидный пример применения GitOps. Как это выглядит:

• Аналитик создаёт AsyncAPI-файл для нового сервиса;
  
• кладёт его в Git и создаёт Merge Request;
  
• автоматический пайплайн:

• проверяет синтаксис (линтинг),
  
• генерирует серверные и клиентские SDK,
  
• разворачивает mock-сервис для QA и фронтов,
  
• публикует интерактивную документацию, например через Swagger UI или Redoc.

• После апрува все артефакты становятся доступны команде. 

Это важный момент: SDK, mock-сервис и документация появляются только после ревью. Значит, команда работает не с «последней версией где-то в чате», а с согласованным состоянием контракта.

Проверка реализации на соответствие контракту 
Когда контракт лежит в Git, его можно использовать в CI для проверки реализации. Рассмотрим на примере: допустим, в контракте поле userId имеет тип string, а разработчик в коде возвращает int. Что можно предпринять?
С Git решение может быть таким:
 

• Пайплайн автоматически сверяет код с контрактом.
  
• Обнаруживает несоответствие типов.
  
• Пайплайн падает и блокирует Merge Request.

Подход будет полезен даже тогда, когда нужно валидировать фрагменты кода из legacy на соответствие контракту.
Также проверка в пайплайне — хорошее решение для кода, написанного на не компилируемых языках. В статически типизированных языках часто достаточно сгенерированного SDK: если типы расходятся, приложение просто не соберётся. В динамических же языках SDK можно обойти, поэтому проверка в CI становится особенно полезной.
Контроль семантического версионирования 
GitOps способен решить и ещё одну достаточно большую боль: версии приложений в целом версионировать достаточно просто, а вот артефакты — сложно. Особенно это играет роль в случае артефактов, для которых важно семантическое версионирование, — например, API-контрактов.
Вот пример распространённой ситуации: аналитик поменял поле, изменил тип со string на int, но в контракте изменил только patch-версию. Но если внедрён GitOps, с помощью инструментов, выявляющих такие обратно несовместимые изменения, можно ещё при автоматической проверке через MR подсветить ошибку до того, как контракт попадёт в работу, или остановить изменение до merge аналитику — чтобы изменил не patch-версию, а мажорную.

Автоматическая публикация документации
Итак, кто-то у нас уже работает в Git — например, разработчики и тестировщики, кого-то — аналитиков и т. д. — можно тоже научить. Но что делать с заказчиками? Наши внутренние и внешние клиенты едва ли сами пойдут в Git читать файлы в Markdown.
Значит, нужно создать для них читаемую документацию, а лучше — ещё и доступную по определённому URL-адресу. И сейчас есть множество инструментов, которые помогут это сделать, — например, MkDocs, Docusaurus, GitBook.
Как это происходит:

• Аналитик пишет документацию в Markdown в Git.
  
• Пайплайн автоматически конвертирует Markdown в HTML и генерирует навигацию и поиск.
  
• Документация публикуется на портале документации.
  
• Все изменения видны в Git diff.

Кстати, я и сам использую этот подход для своего сайта: пишу его в Markdown, а тот генерируется в веб-сайт. 
Проверка безопасности
Git можно использовать для проверки безопасности. Мы берём контракт, в контракте появляется новый метод — DELETE /users/{id}, и мы автоматически проверяем:

• есть ли описание авторизации;
  
• прописаны ли роли и права;
  
• указаны ли ошибки 401/403.

Если нет — MR блокируется.
Впрочем, при внедрении здесь можно столкнуться с проблемой, что у каждой команды есть свои правила, с которыми она работает. Поэтому проверки придётся писать. Но всё равно это не займёт много времени: в пилотном варианте такие проверки вполне реально собрать за пару недель, особенно если использовать ИИ для подготовки правил и тестовых примеров.
Валидация схем данных
Эта проверка проходит так: аналитик меняет ER-диаграмму, на её основе генерируется SQL-миграция, и пайплайн проверяет:

• не теряются ли данные;
  
• есть ли индексы и внешние ключи;
  
• соответствуют ли названия таблиц и полей стандартам команды.

Реализовать это можно с помощью инструментов sqlfluff, скриптов с dry-run на тестовой базе, pgTAP (это тесты для схем).
Обязательные описания коммитов
Если артефакты становятся кодом, то к ним должны применяться те же правила: понятные коммиты, связь с задачей и объяснение причины изменения.
В рамках пайплайна бывает дорого проводить много проверок: чем их больше, тем больше и времени занимает пайплайн. И тем больше циклов «запустили пайплайн — проверили — упал — вернулись, доработали — запушили — опять смотрим пайплайн». И вот тут ситуацию осложняет ещё одна проблема — обилие коммитов с одинаковыми наименованиями, которые появляются просто потому, что люди не понимают, какой коммит и куда писать.
Для решения этой проблемы можно ввести обязательные описания коммитов разработчиков и аналитиков, содержащие связь с задачей (например, номер задачи).
Это возможно с pre-commit hook. Что он делает:
 

• проверяет формат сообщения;
  
• если нет ID задачи или описания — пуш отклоняется.

 
Контроль MR 
С MR тоже часто встречается проблема: когда не описывают подробно, что изменили, и из-за этого возникают несоответствия. Цепочка решения с помощью GitOps в этом случае может быть такой:

• Аналитик заводит MR с новой спецификацией, но забывает описать, что поменялось.
  
• Пайплайн проверяет поле description.
  
• Если в поле пусто — merge невозможен.

А ещё можно добавить шаблоны MR: «что изменено», «зачем изменения», «как изменения повлияют на пользователя».

Обязательные ревью правил

Ещё одна частая неприятная ситуация — когда при совместной работе забывают уведомить остальных участников команды об изменениях. Например, аналитик сделал контракт, потом пришёл разработчик — что-то поменял, но не оповестил остальных. И вот у других разработчиков, тестировщиков SDK генерируются, валидация проходит — ведь контракт изменён и у него корректный SDK.
Как избежать таких проблем? С помощью codeowners, где можно указать владельца файла или папки. При этом владельцем может быть один человек или команда — и тогда без её подтверждения ME в принципе не пройдёт. Так что в вышеописанной ситуации разработчик теперь тоже сможет менять контракты, сделанные аналитиком, но эти изменения должны верифицировать аналитик, техлид или команда, указанная в codeowners.
Но есть нюанс: не стоит назначать обязательных владельцев на всё подряд. Codeowners нужны там, где ошибка действительно дорого стоит: контракты, критичные бизнес-правила, схемы данных, security-требования. Иначе вы будете часто попадать в ситуации, когда тот, кто должен верифицировать изменения, отсутствует — в отпуске, недоступен — и у вас ни один MR не проходит.
Автоматическая генерация Changelog
Генерацию Changelog часто всё ещё делают вручную. Но если мы называем коммиты в соответствии с Conventional Commit, можно внедрить автогенерацию Changelog — для этого есть специальные инструменты.
Как происходит процесс генерации поэтапно: 

• При merge на прод анализируются коммиты;
  
• группируются по типам: features, fixes, breaking changes и т. д.;
  
• формируются:

- Changelog.md в репозитории,
- Release notes в GitLab или GitHub,
- уведомление в мессенджер.
 Всё это генерируется за пару минут, и не нужно вручную писать все изменения, которые были сделаны. Для этого не нужна революция: достаточно договориться о формате коммитов и добавить генератор release notes в пайплайн.
 
Контроль языка и терминологии
Вы с таким тоже наверняка сталкивались — когда в документации пишут «клиент», «пользователь», даже «юзер», но всё это об одном и том же. И таких разночтений может быть сколько угодно.
Если с верификацией контрактов, YAML и подобными файлами немного проще — существуют специальные инструменты, которые их валидируют, — то что делать с огромным пластом обычного текста? Его тоже надо как-то валидировать и приводить к единообразию терминологии.
Что можно предпринять с Git в данном случае? Использовать линтер для документации, который действует таким образом: 

• в репозитории есть глоссарий утверждённых терминов;
  
• Vale или подобный линтер проверяет Markdown;
  
• при использовании запрещённых слов пайплайн возвращает ошибку.

Конечно, здесь не обойтись без дополнительных расходов на поддержание файла в актуальном состоянии, но можно облегчить жизнь, интегрировав в процесс ИИ. 
Шаблоны артефактов 
Как это работает? Аналитик заводит новый контракт, а пайплайн автоматически проверяет: 

• есть ли обязательные разделы (описание, версии, примеры запросов/ответов);
  
• есть ли тестовые примеры и т. д. 

Проще говоря, если мы храним шаблоны артефактов в Git, то можем типизировать все наши основные документы, контракты и генерировать их в рамках самого Git. У нас просто есть определённый пайплайн, где достаточно нажать кнопку — и нужный артефакт уже появился. Или даже целый проект. Мы можем писать только бизнес-логику — и под ней уже будет подразумеваться не только код самого приложения, но документы, контракты и всё, что входит в этот сервис.
Syntetic monitoring (Синтетический мониторинг)
 Более сложная ситуация — проверка прода уже на этапе эксплуатации. Даже при использовании автоматики есть риски, что где-то что-то не учли, что-то не то попало в прод и т. д. И нужно валидировать, действительно ли на проде у нас то, что мы и планировали изначально, или есть какие-то отклонения. Решать эту задачу можно с помощью разных подходов.
Первый подход — периодически проверять прод контрактными тестами: 

• Раз в N минут запускаются тесты на основе контракта в Git;
  
• Проверка соответствия реальных ответов и спецификации;
  
• При расхождении — алерт в мессенджер.

Можно упростить задачу — не писать такие коллекции, а генерировать из контрактов. В этом случае мы можем быть уверены, что в тесты не просочился человеческий фактор. Для этого нам понадобится инструмент Schemathesis, который позволяет генерировать автотесты на основе API-контрактов.
Вот как это выглядит:

Есть и другой подход, но для него важно, чтобы у вас был API Gateway. Потому что в рамках API Gateway возможно проводить валидацию:

• Сначала Kong/Tyk загружает OpenAPI-спецификации из Git.
  
• Затем на каждый запрос Gateway валидирует response.
  
• При несоответствии он логирует warning в ELK/Loki.
  
• Dashboard показывает метрики соответствия.

 В простом сценарии это настраивается довольно быстро, особенно если API Gateway уже является частью платформы. К тому же, что удобно, благодаря логированию можно всегда вернуться. Кроме того, API Gateway не блокирует пользователя.
AI-ассистированное ревью
Когда спецификации и требования лежат в Git, ИИ можно подключать не «поверх процесса», а прямо в MR. В GitOps его возможности тоже можно задействовать для таких задач:

• автоматический анализ изменений в спецификациях;
  
• поиск потенциальных несоответствий;
  
• предложения улучшенных формулировок;
  
• генерация тестовых сценариев из спецификаций;
  
• автоматическое создание базовых test cases;
  
• проверка полноты документации;
  
• поиск пропущенных edge cases;
  
• предложение дополнительных примеров, которые расширят документацию.

Как перейти на GitOps?
Итак, вы видите, что GitOps действительно может решить многие боли и ускорить разработку, повысить её качество — и всё это без постоянного инструктажа аналитиков и разработчиков, как надо и не надо вносить изменения. Но остаётся вопрос: а легко ли внедрить культуру GitOps в компании?
Я отвечу: на самом деле для этого нужно не так уж много. Начать можно просто с контрактов, добавить пайплайн с линтингом и codeowners с превью. И уже через месяц у вас будет процесс, который затем можно спокойно масштабировать и улучшать.
 -Источник