Розробка кастомних 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.
• Виконавці збірок і середовища: спільні чи власні, чи є обмеження щодо мережі, кешу, доступів до зовнішніх ресурсів.
• Критичні стадії перед викочуванням: тести, статичний аналіз, збірка образів, публікація в реєстр — що обов’язково має проходити, а що опціонально.
• Схема роботи із секретами: де лежать облікові дані, хто має право змінювати змінні рівня групи та окремого проєкту.
• Вимоги до сумісності: які гілки та правила злиття підтримуються, чи потрібен окремий набір шаблонів під різні типи продуктів.

Після обговорення повертаємося з картою повторно використовуваних шаблонів і зонами відповідальності в кожному, планом перенесення проєктів без зупинки викочувань, порядком етапів та оцінкою обсягу.

Далі — узгодження пріоритетів і впровадження, починаючи з тих репозиторіїв, де дублювання коштує найдорожче.