Настройка матричных сборок (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 минут. Разница в производительности — до 10 раз.

Проблемы, которые решаем

• Дублирование кода: четыре одинаковых 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. Разработчики ждут результаты минут, а не полчаса.

Сравнение матричных сборок в разных CI-системах

GitHub Actions documentation рекомендует использовать fail-fast: false для тестов совместимости, чтобы получить максимально полную информацию.

Когда нужны матричные сборки?

• 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 раза по сравнению с последовательными. Это особенно критично при активной разработке.

Процесс работы

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

Что входит в работу

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

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

Сроки и стоимость

Добавить matrix strategy к существующему job — от часа. Настроить matrix с exclude, experimental и корректными needs: — полдня. Для монорепозитория с несколькими языками — до 2–3 дней. Стоимость рассчитывается индивидуально в зависимости от сложности матрицы и количества платформ.

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