Saltar al contenido

Matrices de compilación en GitHub Actions, bien hechas

Última actualización

Una matriz de compilación ejecuta el mismo job con combinaciones de sistema operativo, versión de lenguaje u otras variables. Es la forma estándar de probar una biblioteca en varios runtimes, y también una manera sencilla de triplicar la factura sin darse cuenta. Esta guía cubre la sintaxis, las opciones que importan y los controles de coste.

Lo básico

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

Eso crea 2 x 2 = 4 jobs. GitHub limita una matriz a 256 jobs por ejecución de workflow. Pegue su configuración en el expansor de matrices para ver todas las combinaciones antes de hacer push, y lo que costarían.

include y exclude

exclude elimina combinaciones; include añade o amplía combinaciones.

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    node: [20, 22]
    exclude:
      - os: macos-latest
        node: 20
    include:
      - os: ubuntu-latest
        node: 24
        experimental: true

Hay dos reglas que suelen generar confusión. Primero, las entradas de include se procesan después de exclude. Segundo, una entrada include cuyas claves coinciden con una combinación existente añade valores extra a esa combinación (sin sobrescribir los valores originales); una que no coincide con nada se convierte en un job nuevo. Añada una clave distinta (como experimental arriba) y léala con ${{ matrix.experimental }}.

fail-fast y max-parallel

Por defecto, fail-fast es true: cuando falla un job, GitHub cancela los demás que siguen en ejecución. Eso ahorra minutos, pero oculta información, ya que solo se entera de una combinación fallida. Use:

  • fail-fast: false para bibliotecas y matrices de compatibilidad, donde quiere la imagen completa.
  • fail-fast: true (el valor por defecto) para matrices de fragmentos de una misma suite, donde cualquier fallo ya implica que la ejecución se pierde.
strategy:
  fail-fast: false
  max-parallel: 4

max-parallel limita los jobs concurrentes de la matriz, útil cuando los jobs comparten un recurso, como una base de datos de pruebas o un límite de peticiones a una API, o para dejar concurrencia libre a otros workflows. Por defecto se ejecutan tantos como permita el plan.

Marque una combinación como autorizada a fallar con continue-on-error: ${{ matrix.experimental == true }} a nivel de job.

Mantenga el coste bajo control

El tamaño de la matriz multiplica los minutos facturados, y el sistema operativo elegido multiplica el precio. Según la tarifa de runners de GitHub, un minuto de Windows cuesta $0.010 y uno de macOS $0.062, frente a $0.006 de Linux; y en los minutos incluidos, Windows cuenta doble y macOS diez veces más. Compare estas dos matrices, cada una con 10 minutos por job:

MatrizJobsCoste por ejecución
3 SO x 4 versiones de Node, todas las combinaciones124 x (10 x 0.006 + 10 x 0.010 + 10 x 0.062) = $3.12
Linux x 4 versiones, más Windows y macOS en latest64 x 0.06 + 0.10 + 0.62 = $0.96

Use la calculadora de costes de Actions para probar con sus propios datos. Formas de reducir una matriz sin perder cobertura real:

  • Pruebe los extremos, no cada celda. Las versiones más antigua y más reciente soportadas detectan la mayoría de los errores de compatibilidad. Ejecute el conjunto completo según una programación en lugar de en cada push.
  • Los sistemas operativos más costosos, una sola vez. Ejecute Windows y macOS con una sola versión del lenguaje.
  • Dos niveles. Una matriz pequeña en los PR; la matriz completa en main y de forma nocturna.
  • Omita según las rutas modificadas para que un cambio en la documentación no ejecute nada.
  • Cancele las ejecuciones reemplazadas con concurrency, algo que importa más a medida que crece la matriz.

Matrices dinámicas

Genere la matriz en un primer job cuando depende del estado del repositorio, por ejemplo solo los paquetes modificados en un monorepo:

jobs:
  plan:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set.outputs.matrix }}
    steps:
      - uses: actions/checkout@v4
      - id: set
        run: echo "matrix=$(node scripts/affected.mjs)" >> "$GITHUB_OUTPUT"
  build:
    needs: plan
    if: ${{ needs.plan.outputs.matrix != '[]' }}
    runs-on: ubuntu-latest
    strategy:
      matrix:
        package: ${{ fromJSON(needs.plan.outputs.matrix) }}
    steps:
      - run: npm run build -w ${{ matrix.package }}

Si la matriz generada está vacía, el job falla con un error, por eso existe la guarda if. Véase también CI para monorepos con Nx o Turborepo.

Checks obligatorios y matrices

La protección de ramas compara los nombres de los checks. Los jobs de la matriz reciben nombres como test (ubuntu-latest, 20), y cualquier cambio en la matriz cambia esos nombres, dejando los checks obligatorios atascados en "Expected". Dé nombres explícitos a los jobs de la matriz si necesita exigirlos o, mejor aún, añada un job de resumen que dependa de toda la matriz y exija solo ese:

  all-tests:
    if: always()
    needs: test
    runs-on: ubuntu-latest
    steps:
      - run: test "${{ needs.test.result }}" = "success"

Use if: always() para que el job de resumen se ejecute y falle cuando falle la matriz; de lo contrario se omite, y un job omitido puede satisfacer un check obligatorio. Más sobre esto en colas de fusión de GitHub.

Uso seguro de los valores de la matriz

Los valores de la matriz también son expresiones. Si alguno procede de una entrada no confiable, como una etiqueta de PR, páselo mediante env en lugar de incrustarlo en los scripts; véase cómo proteger GitHub Actions. Además, entrecomille las versiones en YAML: python: [3.9, 3.10] interpreta 3.10 como el número 3.1. Escriba ["3.9", "3.10"].

Claves de caché por celda

Incluya los valores de la matriz en las claves de caché para que las celdas no se sobrescriban entre sí:

key: npm-${{ matrix.os }}-node${{ matrix.node }}-${{ hashFiles('package-lock.json') }}

Muchas celdas escribiendo cachés grandes pueden llenar el límite de 10 GB por repositorio. Véase la guía de caché.

Preguntas frecuentes

¿Cuál es el tamaño máximo de una matriz?

256 trabajos por ejecución de flujo de trabajo, según los límites de uso de GitHub.

¿Puede una matriz incluir trabajos en distintos runners?

Sí, configure runs-on: ${{ matrix.os }} o incluya una clave runner en cada entrada. Las etiquetas de runners grandes también funcionan.

¿Cómo asigno nombres a los trabajos de la matriz?

Configure name: test (${{ matrix.os }}, node ${{ matrix.node }}) a nivel de trabajo para obtener nombres de comprobación legibles.

¿Por qué mi entrada include crea un trabajo nuevo?

Porque no coincide con una combinación existente en todas las claves originales. Revise si hay erratas y diferencias de tipo, como 20 frente a "20".

Pruébelo con su matriz

Cuando una matriz tarda mucho, la velocidad de cada celda importa tanto como su número. El modo de comparación de compiler.dev ejecuta una celda en máquinas más rápidas, para que pueda ver el tiempo de ejecución y el coste por celda antes de cambiar nada.

Ejecute este workflow en compiler.dev Sin tarjeta · 200 minutos gratuitos

Pruébelo gratis