O Que É um Matrix Build no GitHub Actions?

Um matrix build expande um job em vários, executando-o uma vez por combinação de variáveis que você define.

Quando você precisa testar em várias versões de linguagem ou sistemas operacionais, uma matrix evita que você copie o job. Você lista as variáveis e o GitHub gera e executa cada combinação em paralelo.

O que é

Uma matrix é definida sob strategy.matrix. Cada chave é uma variável com uma lista de valores; o GitHub cria um job por combinação.

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [18, 20, 22]
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm test

Como funciona

O GitHub calcula o produto cartesiano das variáveis da matrix e lança um job paralelo para cada uma. Dentro do job você lê os valores com ${{ matrix.<key> }}.

Includes e excludes

Você pode adicionar combinações extras específicas com include ou remover as indesejadas com exclude, dando controle fino sobre quais células realmente executam.

Por que importa

Matrizes dão ampla cobertura de forma barata: um bloco conciso testa muitos ambientes de uma vez. Fique atento ao tamanho, porém, pois as combinações se multiplicam e podem consumir muitos minutos de runner.

Conceitos relacionados

Uma matrix é controlada pela chave strategy e interage com fail-fast, que decide se uma célula que falha cancela as demais.

Principais conclusões

• Uma matrix executa um job em várias combinações de variáveis.
• Leia os valores com ${{ matrix.key }}.
• Use include/exclude e fique atento à contagem de combinações.

Guias relacionados