Guía9 min

strategy.matrix en GitHub Actions: no clones el job a mano

Resumen

jobs.<id>.strategy.matrix expande OS/Node en N jobs. fail-fast true cancela el resto al primer fallo. Un agente que copia 4 jobs ubuntu/windows a mano duplica YAML y olvida un OS. Distinct de concurrency. Docs GitHub workflow syntax strategy.

GitHub
Una matrix node x os, no cuatro jobs copiados

Qué resuelve

Esta pieza se queda en la decisión práctica: qué instalar, qué riesgo agrega y cómo aplicarlo sin romper operación.

Cuatro jobs test-node20, test-node22 copiados es deuda. strategy.matrix genera la combinación. Cada celda es un job con matrix.node.

No es concurrency (cancela runs de la misma rama). El curso instalar un agente no cubre matrix. gh pr no sustituye un matrix de CI.

Receta

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

fail-fast: true (default) mata el resto al primer rojo. En PRs de agentes: false, quieres ver si falló solo Node 20.

max-parallel acota minutos. Un matrix 5×4 sin techo quema Actions.

fail-fast false para ver todos los OS

Qué no hacer

  • include/exclude de más para “un caso raro” que cabe en un job aparte.
  • Secrets distintos por celda sin Environment. El matrix no es un ACL.
  • matrix.os + runs-on: ubuntu-latest fijo: el OS de la matrix no aplica.

continue-on-error en una celda experimental, no en todo el job de prod.

Receta AGENTS.md

Use strategy.matrix instead of copied jobs.
fail-fast: false on PR CI unless the ticket says otherwise.
Cap max-parallel. Reference matrix.* in steps, not hardcoded versions.

max-parallel vs explosion de celdas

FAQ

¿Windows + pnpm? runner.os en cache keys. No asumas paths unix.

¿Un job depende de toda la matrix? needs: test espera todas las celdas.

¿matrix from JSON? fromJSON existe. Un agente que genera 80 celdas desde un comment del PR es un DoS de minutos.

Verificado 2026-09-03 contra GitHub workflow syntax jobs.<job_id>.strategy y using a matrix for your jobs.