O que é um build matrix? Testando em várias versões e plataformas

Por Kaveh Alemi·Latchkey

Uma matrix transforma uma definição de job em muitos jobs paralelos - um por combinação das variáveis que você lista - para você testar em várias versões e plataformas sem copiar e colar jobs.

Um build matrix é uma forma compacta de espalhar um único job por uma grade de configurações. É assim que você prova que seu código funciona em múltiplos SOs, versões de linguagem ou conjuntos de dependências de uma vez.

Como uma matrix funciona

Você declara variáveis com listas de valores; o sistema de CI gera o produto cartesiano - um job por combinação - e os roda em paralelo. Uma matrix 3-OS × 3-versões expande para nove jobs, cada um uma execução isolada dos mesmos steps.

2 × 3 = 6 jobs

strategy:
  matrix:
    os: [ubuntu-latest, macos-latest]
    node: [18, 20, 22]

Por que é útil

Pegar bugs específicos de versão e plataforma antes dos usuários.
Paralelizar a cobertura em vez de rodar combinações em série.
Expressar testes amplos de compatibilidade em poucas linhas de config.

O multiplicador de custo

Uma matrix multiplica os minutos cobráveis pelo número de combinações. Uma matrix ampla de jobs curtos também é punida pelo arredondamento de minuto por job. Corte combinações que agregam pouco sinal (use include/exclude para testar só pares significativos) em vez de testar cegamente a grade inteira.

Matrix e fail-fast

Por padrão, muitos sistemas cancelam o resto da matrix quando um job falha (fail-fast). Isso economiza minutos, mas oculta se a falha é específica de uma combinação. Desabilite o fail-fast quando precisar ver a grade completa de pass/fail em todas as configurações.

Principais conclusões

Uma matrix expande um job no produto cartesiano de suas variáveis.
Ela roda combinações em paralelo para cobertura cross-plataforma rápida.
O custo escala com o número de combinações - pode as de baixo sinal.
fail-fast cancela os jobs irmãos na primeira falha; desabilite para ver a grade completa.

Perguntas frequentes

What is What is a build Matrix? testing across versions and platforms?

A build matrix is a compact way to fan a single job out across a grid of configurations. It is how you prove your code works on multiple OSes, language versions, or dependency sets at once.

How a matrix works?

You declare variables with lists of values; the CI system generates the Cartesian product - one job per combination - and runs them in parallel. A 3-OS × 3-version matrix expands to nine jobs, each an isolated run of the same steps.

The cost multiplier?

A matrix multiplies billable minutes by the number of combinations. A wide matrix of short jobs is also punished by per-job minute rounding. Trim combinations that add little signal (use include/exclude to test only meaningful pairs) rather than blindly testing the full grid.

Matrix and fail-fast?

By default many systems cancel the rest of the matrix when one job fails (fail-fast). That saves minutes but hides whether the failure is specific to one combination. Disable fail-fast when you need to see the full pass/fail grid across all configurations.

Guias relacionados

What Is a GitHub Actions Workflow? Jobs, Steps, and TriggersA GitHub Actions workflow is a YAML file that defines when and how your CI runs. Fail-Fast vs Continue-on-Error: Controlling How CI StopsFail-fast stops the pipeline at the first failure; continue-on-error lets it press on. What Is Fan-Out / Fan-In in CI Pipelines?Fan-out splits work into many parallel jobs; fan-in collects their results into one.