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

> Um build matrix roda o mesmo job em muitas combinações - OS, versão de linguagem, conjunto de dependências. Entenda como matrizes funcionam e como multiplicam o custo.

Source: https://latchkey.dev/pt/learn/ci-cd-concepts/what-is-a-build-matrix  
Updated: 2026-06-25

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.

## FAQ

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt