Saltar al contenido

¿Qué es una compilación de matriz en GitHub Actions?

Última actualización

Una compilación matricial es una estrategia de GitHub Actions que expande una definición de job en muchos jobs paralelos, uno por cada combinación de las variables que indique, como el sistema operativo y la versión del lenguaje.

Cómo funciona

Añade strategy.matrix a un job e indique valores para una o más claves. GitHub crea un job por cada combinación, cada uno en su propio runner. Dentro del job, lea los valores actuales con ${{ matrix.<key> }}.

Dos listas de tres valores generan nueve jobs. El número crece rápidamente y cada job consume minutos de CI, por lo que una matriz amplia puede resultar costosa.

Ejemplo

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [20, 22]
        include:
          - os: ubuntu-latest
            node: 24
        exclude:
          - os: windows-latest
            node: 20
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm ci && npm test

Opciones útiles

  • include añade combinaciones adicionales o variables extra a las existentes.
  • exclude elimina las combinaciones que no desea.
  • fail-fast (por defecto true) cancela los jobs restantes cuando uno falla. Configúrelo en false si desea el resultado completo.
  • max-parallel limita cuántos jobs de la matriz se ejecutan al mismo tiempo.

Puede previsualizar la expansión con la herramienta de expansión de matrices. La guía completa está en compilaciones matriciales de GitHub Actions.

Errores comunes

  • Usar una matriz cuando no es necesaria. Probar tres versiones de Node para una aplicación que solo se distribuye en una desperdicia minutos.
  • Mantener fail-fast activado mientras depura. Un job inestable cancela los demás y oculta los fallos reales.
  • Usar una matriz para acelerar. Una matriz de jobs idénticos no reparte el trabajo. Para dividir un conjunto de pruebas entre varias máquinas, use sharding de pruebas.
  • Demasiadas comprobaciones obligatorias. Cada ramificación de la matriz es una comprobación con nombre propio, lo que complica la protección de ramas.
  • Superar los límites. Una matriz está limitada a 256 jobs por ejecución de workflow.

Preguntas frecuentes

¿Cuál es la diferencia entre una matriz y el sharding de pruebas?

Una matriz ejecuta el job completo con distintas configuraciones. El sharding divide las pruebas de una misma configuración en fragmentos. Ambos pueden combinarse usando un índice de fragmento como variable de la matriz.

¿Una matriz ejecuta los jobs en paralelo?

Sí, en la medida en que lo permitan la capacidad de los runners y los límites de concurrencia. Use max-parallel para limitarlo.

¿Puede generarse la matriz de forma dinámica?

Sí. Un job puede generar JSON y un job posterior lo lee con fromJSON en strategy.matrix.