Привет, Хабр! Сегодня мы часто говорим про разные тренды в разработке — ИИ‑агентов, тестирование на ранних стадиях, прослеживаемость изменений, автоматизацию пайплайнов… Все эти тренды звучат убедительно, пока не упираются в реальность: требования лежат в на общих дисках, схемы — в картинках, контракты — в разных версиях, а история изменений размазана по инструментам.

Что делать с этим?

Лев Немировский, руководитель направления по развитию инструментов внедрения ПСБ, рассказал, чем полезен в этом случае подход 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 с превью. И уже через месяц у вас будет процесс, который затем можно спокойно масштабировать и улучшать.