Налаштування матричних збірок (Matrix Builds) у CI/CD

Ми — команда DevOps-інженерів із 5+ років досвіду в CI/CD. Налаштування матричних збірок (Matrix Builds) — завдання, з яким стикається кожен DevOps під час підтримки мультиплатформних проєктів. Уявіть: ви розробляєте Python-бібліотеку, яка має працювати з версіями 3.9, 3.10, 3.11, 3.12 під Ubuntu, Windows та macOS. Без матриці доводиться писати 12 однакових job (4 версії × 3 ОС) або запускати їх послідовно — пайплайн розтягується на 60+ хвилин, а розробники чекають. З матричною збіркою один yaml-конфіг генерує 12 паралельних job, і повний звіт про сумісність готовий за 5–7 хвилин. Матрична збірка в 4 рази швидше за послідовну, що критично при активній розробці.

Проблеми, які вирішуємо

• Дублювання коду: чотири однакові job з різними версіями — джерело помилок і складності підтримки.
• Довгі пайплайни: послідовний запуск 4–5 версій множить час очікування розробників.
• Втрата контексту: при провалі одного тесту зупиняються всі інші, і ви не бачите повної картини.

Матричні збірки вирішують усі три проблеми декларативно.

Як налаштувати матричну збірку в GitHub Actions?

---
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.9", "3.10", "3.11", "3.12"]
        os: [ubuntu-latest, windows-latest]
      fail-fast: false
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - run: pip install -e ".[test]" && pytest
---

fail-fast: false — важлива деталь. За замовчуванням GitHub Actions зупиняє всі інші matrix jobs при першому провалі. Для тестування сумісності це небажано: потрібно побачити, на яких версіях тест падає, а на яких проходить. Результат: 8 паралельних jobs (4 версії Python × 2 ОС).

Що таке виключення та включення в матриці?

Не всі комбінації мають сенс. Python 3.9 на Windows із певними залежностями може не підтримуватися взагалі:

---
strategy:
  matrix:
    python-version: ["3.9", "3.10", "3.11", "3.12"]
    os: [ubuntu-latest, windows-latest]
    exclude:
      - python-version: "3.9"
        os: windows-latest
    include:
      - python-version: "3.12"
        os: ubuntu-latest
        experimental: true

include дозволяє додати додаткові змінні до конкретних комбінацій. Тут experimental: true — кастомна змінна, яку можна використовувати в continue-on-error: ${{ matrix.experimental }}. Experimental jobs не провалять увесь workflow, навіть якщо впадуть.

GitLab CI: parallel:matrix

У GitLab матричні збірки реалізовані через parallel:matrix:

---
test:
  image: python:${PYTHON_VERSION}
  parallel:
    matrix:
      - PYTHON_VERSION: ["3.9", "3.10", "3.11", "3.12"]
        DATABASE: ["postgresql", "sqlite"]
  script:
    - pip install -e ".[test]"
    - pytest --database $DATABASE
---

GitLab створює 8 jobs з іменами виду test: [3.9, postgresql], test: [3.9, sqlite] тощо. Усі виконуються паралельно в межах однієї стадії. Окрема потужна можливість — матриця для multi-architecture Docker builds:

---
build:
  parallel:
    matrix:
      - ARCH: [amd64, arm64]
        PLATFORM: [linux/amd64, linux/arm64]
        script:
          - docker buildx build --platform $PLATFORM -t myapp:${CI_COMMIT_SHORT_SHA}-${ARCH} --push .

Після цього створюється multi-arch manifest: docker manifest create myapp:latest myapp:sha-amd64 myapp:sha-arm64.

Як вибрати fail-fast та continue-on-error?

Параметр fail-fast: false — не просто прапорець, а гарантія, що ви отримаєте повну картину сумісності. Без нього перший упавший тест перериває всі інші, і ви витрачаєте час на фікс, не знаючи, чи працює код на інших версіях. Налаштування continue-on-error для експериментальних комбінацій дозволяє тестувати нові версії без ризику заблокувати pipeline. Приклад: якщо ви тестуєте Python 3.13 (ще нестабільний) разом із старими версіями, увімкніть experimental: true та continue-on-error. Тоді падіння на новинці не зупинить перевірку на 3.9–3.12.

Порівняння: матрична vs послідовна збірка

На практиці різниця в швидкості особливо помітна, коли за день проходить 10–20 PR. Розробники чекають результати хвилини, а не півгодини. Також варто враховувати параметр fail-fast: false для тестів сумісності — це запобігає передчасному зупиненню всіх jobs.

Порівняння матричних збірок у різних CI-системах

Коли потрібні матричні збірки?

• Multi-runtime бібліотеки: Python-пакет під 3.9–3.12, PHP-пакет під 7.4–8.2.
• Кроссплатформні застосунки: Node.js під Linux, Windows, macOS.
• Docker multi-arch: збірка образів під amd64 та arm64 для підтримки Raspberry Pi та ARM-серверів.

Матричні збірки скорочують час тестування в 4 рази порівняно з послідовними. Використання fail-fast: false дозволяє отримати повну картину сумісності в 4 рази швидше, ніж при послідовному тестуванні. Це особливо критично при активній розробці.

Процес роботи

1. Аналіз: визначаємо список версій, архітектур, ОС для тестування.
2. Проєктування: обираємо CI-систему та розробляємо матрицю з виключеннями та експериментальними комбінаціями.
3. Реалізація: пишемо конфігурацію, налаштовуємо кешування залежностей, паралельні runners.
4. Тест: запускаємо повний matrix, перевіряємо коректність падіння/проходження.
5. Деплой: інтегруємо матрицю в існуючий CI/CD, документуємо.

Що входить в роботу під ключ

• Конфігурація matrix strategy під ваш стек.
• Налаштування виключень та включень для несумісних комбінацій.
• Оптимізація часу: кешування, розпаралелювання stages.
• Документація з додавання нових версій.
• Навчання команди: як читати матричні звіти, додавати комбінації.

Досвід наших інженерів — 5+ років у CI/CD, понад 50 проєктів з матричними збірками. Ми гарантуємо, що пайплайн не дублюватиме код, а час тестування скоротиться в 2–4 рази.

Терміни та вартість

Додати matrix strategy до існуючого job — від 1 години (3000 грн). Налаштувати matrix з exclude, experimental та коректними needs: — півдня (6000 грн). Для монорепозиторію з кількома мовами — до 2–3 днів (від 15000 грн). Оцінимо ваш проєкт — пишіть нам! Економія часу: один PR з матричною збіркою замість послідовної економить до 15 хвилин, що при 20 PR на день дає 5 годин щодня (150 годин на місяць).

Зв'яжіться з нами для консультації — налаштуємо матричні збірки під ваш проєкт. Замовте налаштування CI/CD та отримайте паралельний запуск тестів без дублювання коду.