Разработка кастомных GitLab CI Templates для переиспользования

Почему GitLab CI Templates разносятся копипастом по репозиториям

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

Цена проявляется не сразу. Пока правки точечные, дублирование настроек сборки незаметно, но первое же изменение — новая проверка безопасности, смена реестра образов, другие правила запуска — превращается в ручной обход всех репозиториев. Что-то забыли, где-то применили наполовину, и расхождение окружений становится нормой: одинаковый код собирается в одном проекте и падает в другом.

Механизмы переиспользования в GitLab — include, extends, !reference — сами по себе проблему не решают. Пока не определён владелец шаблона, схема версионирования и правило обновления проектов, файл-образец снова уезжает копией. Тогда поддержка множества репозиториев держится на людях, а не на конфигурации.

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

Единый слой сборочных заготовок: эффект в цифрах

Переход на единый слой заготовок измеряется не ощущением «стало чище», а числами из истории сборочных схем. Ниже — то, что мы фиксируем до и после внедрения общей библиотеки заготовок в GitLab: снимки метрик снимаем на одних и тех же проектах, чтобы сравнение было честным.

• Время сборки. Типовой сервис собирается за 4–6 минут вместо 20–30: заготовка подтягивает общий кэш зависимостей и не переустанавливает окружение с нуля на каждом шаге.
• Доля ручных правок. Правки в сборочные файлы падают с десятков за месяц до единиц — изменение вносят один раз в заготовку, и оно расходится по всем проектам.
• Устранённый класс отказов. Расхождение версий инструментов и параметров между репозиториями исчезает: сборка перестаёт «работать у одного инженера и падать у другого».
• Время восстановления. Откат заготовки к предыдущей ревизии возвращает рабочую сборку за минуты, без ручной правки десятка файлов и поиска, что именно сломалось.
• Сопровождение сборочных схем. Новый репозиторий подключается к заготовке одним изменением в файле настроек — вместо копирования чужой схемы и её адаптации под себя.
• Доля покрытых проверок. Обязательные шаги — статический анализ, тесты, проверка зависимостей — приходят из заготовки и не могут быть случайно пропущены в отдельном проекте.

Итог: сборочный слой перестаёт быть набором частных решений и становится управляемым — его меняют в одном месте, а эффект виден во всех проектах сразу.

GitLab CI Templates: сравнение подходов к переиспользованию

В GitLab CI общий слой заготовок собирают несколькими способами, и выбор между ними определяется двумя числами: сколько репозиториев на обслуживании и насколько дорого стоит сорванная сборка. На двух-трёх проектах дешевле локальные сборочные схемы. Дальше правка одного правила превращается в N одинаковых коммитов, а версии правил в проектах расходятся.

Разница между библиотекой и версионируемыми заготовками не косметическая. Библиотека без версионирования становится точкой отказа: первый же неудачный коммит останавливает сборки во всех проектах сразу. Заготовка со ссылкой на тег даёт то же переиспользование, но оставляет проекту право обновиться по своему графику и вернуться на предыдущий тег.

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

От аудита репозиториев до передачи библиотеки: этапы работ

Порядок работ построен так, чтобы решение опиралось на данные репозиториев, а не на предположения. Сначала фиксируем текущее состояние, затем проектируем общий слой и проверяем его на ограниченной группе проектов — и только после этого библиотека GitLab CI Templates уходит во все команды.

1. Аудит репозиториев. Проходим по всем проектам организации, выгружаем конфигурации, отмечаем дубли, ручные шаги и расхождения между командами. На выходе — карта: где логика повторяется, а где противоречит сама себе.
2. Инвентаризация сборочных схем. Сводим найденное в таблицу: триггеры, стадии, кэш, артефакты, правила окружений. Видно, какие блоки становятся общим шаблоном, а какие остаются проектными.
3. Проектирование слоя шаблонов. Делим библиотеку на уровни: базовый, языковой, прикладной. Отдельно фиксируем, что обязано быть единым, а что команда вправе переопределить у себя без согласования.
4. Сборка и версионирование. Пишем шаблоны и проверяем их на совместимость с уже настроенными сборками. Каждое изменение получает версию, поэтому обновление библиотеки не ломает проекты, которые ещё не готовы к переходу.
5. Пилотная группа проектов. Подключаем несколько репозиториев с разным стеком и сравниваем время сборки, долю падений и число ручных правок до и после. Расхождения разбираем до передачи в остальные команды.
6. Передача библиотеки и обучение. Оформляем документацию: как подключить, как расширить, что делать при откате. Разбираем с командами порядок правок, чтобы изменения шли через шаблон, а не копированием между репозиториями.

После передачи библиотека живёт самостоятельно: новый проект подключается к общему слою за один шаг, а правила обновляются в одном месте. Это и есть точка, в которой сопровождение сборочных схем перестаёт зависеть от конкретного инженера.

Что остаётся у вас: артефакты, политики, документация

Внедрение закончено не тогда, когда конвейер сборки отработал без ошибок, а когда команда меняет его сама, без нас. Поэтому на выходе — не набор скриптов в переписке, а версионируемый репозиторий шаблонов GitLab CI с описанием, политиками и регламентом правки. Всё лежит в вашем контуре и под вашими учётными записями, доступы выдаются штатным ролям. Ниже — что именно передаём на руки.

• Репозиторий шаблонов с нумерацией мажорных версий: сервисы подключают нужную ветку, обновление не ломает чужие сборки.
• Конфигурации этапов: подготовка окружения, сборка, статические проверки, тесты, публикация артефактов и образов.
• Правила наследования: какие параметры проект переопределяет сам, а какие обязан унаследовать из общего шаблона.
• Политики доступа: отдельные роли на правку шаблонов, на подключение и на просмотр; защита основной ветки и обязательное согласование изменений.
• Схема зависимостей: какой сервис на какую версию шаблона опирается и что отвалится при правке общего файла.
• Документация по сборке: обязательные переменные, примеры подключения, разбор типовых ошибок и их причин.
• Регламент изменений: как предложить правку, кто согласует, как выкатывается новая версия и как откатиться на предыдущую.
• Инструкция по разбору упавшей сборки и запись финального разбора с вашей командой — контекст остаётся у вас, а не у нас.

Кейс: 40 репозиториев и один слой сборочных заготовок

Проект — 40 репозиториев одной продуктовой команды, и в каждом лежал свой файл сборки. Схемы копировали из соседнего репозитория: к моменту разбора общих строк между копиями оставалось меньше, чем расхождений, а правка одной стадии означала 40 отдельных изменений.

Что было

Никто не мог точно сказать, чем сборка одного сервиса отличается от другого. Обновление образа или правил кеширования превращалось в рейд по всем репозиториям: часть правок забывали, часть вносили по-разному, и сборка вела себя непредсказуемо. Восстановление упавшей сборки занимало около четырёх часов — инженер сначала искал, какая из копий сломалась.

Что изменили

Вынесли общий слой заготовок на GitLab CI Templates: стадии, правила кеша, публикация артефактов и проверки живут в одном наборе шаблонов, а в репозитории остался короткий файл, который подключает нужный набор и переопределяет параметры. Каждый сервис описывает только то, что в нём действительно своё.

Дубли схем сократились в десять раз, и это не разовая уборка: новый шаблон подключается одной строкой, поэтому копии снова не расползутся. Новый сервис получает рабочую сборку в первый день вместо недели копирования чужого файла.

Чем отличаются общие заготовки от схем под каждый проект?

В GitLab CI общая заготовка описывает инвариант — то, что одинаково в большинстве репозиториев: установка зависимостей, прогон тестов, сборка артефакта, публикация в реестр. Проектная схема добавляет то, что зависит от репозитория: набор окружений, ветки запуска, матрицу сборок и правила отката. Граница между ними проходит там, где правило перестаёт повторяться.

Практический критерий простой: если правило отличается в двух проектах из трёх, его место — в проектной схеме; если совпадает везде, оно поднимается в общую заготовку. Заготовка при этом параметризуется — образ, стадия, имя артефакта передаются снаружи, — иначе она быстро превращается в набор условий под каждый репозиторий.

Проектная схема остаётся тонким слоем в несколько десятков строк и только подключает общие заготовки. Тогда правка политики сборки делается в одном месте, а не в сорока файлах, и нестандартный проект не тянет за собой остальные.

Частые технические вопросы про общие сборочные заготовки

Большинство сомнений технических руководителей сводится к четырём вопросам: не сломает ли общая заготовка текущие сборки, как переводить существующие конфигурации, кто вправе менять общий код и как откатить изменение, если оно уже разошлось по десяткам проектов. Отвечаем по существу.

Заготовка — это обычный файл конфигурации сборочной цепочки, подключаемый по ссылке; она задаёт базу, а проектные настройки остаются приоритетными.

Как перевести на шаблон существующую конфигурацию?

Инкрементально: сначала выносим общие скрипты сборки, затем стадии, кэш и артефакты — каждый шаг отдельным изменением. Старая конфигурация продолжает работать, пока новый вариант не подтвердится серией прогонов, и переключение остаётся обратимым на любом шаге.

Кто может менять общий шаблон?

Репозиторий шаблонов закрыт: право на изменение — у ограниченного круга инженеров, ветка защищена, обязательны проверки и согласование владельцев кода. Проекты подключают заготовку только на чтение, поэтому правка в одном из них не задевает остальные.

Как откатить неудачное изменение?

Ссылка привязана к тегу, а не к плавающей ветке, поэтому откат — это возврат тега в проекте или выпуск исправленного. Синхронно править десятки конфигураций и переписывать историю не требуется.

Обсудим задачу: что нужно от вас и что делаем мы

Чтобы оценка была реалистичной, а не «плюс-минус порядок», нам нужно увидеть текущее состояние репозиториев и понять, как устроены ваши процессы сборки и выкатки. Опишите задачу — вернёмся с составом шаблонов, планом работ и оценкой объёма.

Что помогает на входе:

• Перечень проектов и типов сборки: какие стеки используются, сколько репозиториев, где сборка отличается принципиально, а где отличается только набором команд.
• Текущие файлы конфигурации и подключённые include — по ним видно дублирование стадий и блоки, которые сворачиваются в общие шаблоны GitLab CI.
• Исполнители сборок и окружения: общие или собственные, есть ли ограничения по сети, кэшу, доступам к внешним ресурсам.
• Критичные стадии перед выкаткой: тесты, статический анализ, сборка образов, публикация в реестр — что обязано проходить, а что опционально.
• Схема работы с секретами: где лежат учётные данные, кто имеет право менять переменные уровня группы и отдельного проекта.
• Требования к совместимости: какие ветки и правила слияния поддерживаются, нужен ли отдельный набор шаблонов под разные типы продуктов.

После обсуждения возвращаемся с картой переиспользуемых шаблонов и зонами ответственности в каждом, планом переноса проектов без остановки выкаток, порядком этапов и оценкой объёма. Дальше — согласование приоритетов и внедрение, начиная с тех репозиториев, где дублирование стоит дороже всего.