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: falsepara 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:
| Matriz | Jobs | Coste por ejecución |
|---|---|---|
| 3 SO x 4 versiones de Node, todas las combinaciones | 12 | 4 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 latest | 6 | 4 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
mainy 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.
Relacionado
- Acelere las compilaciones de Xcode en CIxcodebuild más rápido en GitHub Actions: caché de SPM y CocoaPods, build-for-testing, configuración de simuladores y qué excluir de las caché de DerivedData.
- ¿Qué es una compilación de matriz en GitHub Actions?Una matrix build ejecuta un job varias veces con distintas entradas, como SO o versión de lenguaje. Aprenda la sintaxis, include/exclude y errores comunes.
- Acelere un monorepo de TypeScript en GitHub ActionsAcelere la comprobación de tipos y el linting en un monorepo TypeScript con GitHub Actions: tsc incremental, referencias de proyecto y cachés.
- Acelere Playwright en un monorepo con GitHub ActionsAcelere las pruebas e2e de Playwright en un monorepo Node con GitHub Actions: compile la app una vez y omita e2e si no cambió.