¿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
includeañade combinaciones adicionales o variables extra a las existentes.excludeelimina las combinaciones que no desea.fail-fast(por defectotrue) cancela los jobs restantes cuando uno falla. Configúrelo enfalsesi desea el resultado completo.max-parallellimita 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-fastactivado 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.
Términos relacionados
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.
Relacionado
- ¿Docker build lento en CI? Encuentre la causa y solúvala¿Builds de Docker lentos en CI? Revise el tamaño del contexto, .dockerignore, el orden de capas, fallos de caché y BuildKit. Corrija primero lo más costoso.
- Matrices de compilación en GitHub Actions, bien hechasUse strategy.matrix con include, exclude, fail-fast y max-parallel, controle el número de jobs y el coste, y configure bien los checks obligatorios.
- ¿Qué es una caché remota de compilación?Una caché de build remota guarda las salidas de tareas de Nx, Turborepo, Gradle y Bazel para que CI y el equipo omitan trabajo ya hecho. Así funciona.
- ¿Qué son los minutos de CI? Facturación de GitHub ActionsLos minutos de CI son el tiempo de cómputo facturado que usan sus pipelines. Cómo GitHub Actions cuenta los minutos y reduzca su consumo.