Acerca de las estrategias de matriz
Una estrategia de matriz permite usar variables en una definición de trabajo para crear automáticamente varias ejecuciones de trabajos basadas en las combinaciones de las variables. Por ejemplo, puedes usar una estrategia de matriz para probar el código en varias versiones de un lenguaje o en varios sistemas operativos.
Uso de una estrategia de matriz
Use jobs.<job_id>.strategy.matrix definir una matriz de diferentes configuraciones de trabajo. En la matriz, define una o más variables seguidas de una matriz de valores. Por ejemplo, la matriz siguiente tiene una variable llamada version con el valor [10, 12, 14] y una variable llamada os con el valor [ubuntu-latest, windows-latest]:
jobs:
example_matrix:
strategy:
matrix:
version: [10, 12, 14]
os: [ubuntu-latest, windows-latest]
Se ejecutará un trabajo para cada combinación posible de las variables. En este ejemplo, el flujo de trabajo ejecutará seis trabajos, uno por cada combinación de las variables os y version.
De forma predeterminada, GitHub Enterprise Cloud maximizará el número de trabajos ejecutados en paralelo en función de la disponibilidad del ejecutor. El orden de las variables de la matriz determina el orden en el que se crean los trabajos. La primera variable que definas será el primer trabajo que se cree en tu ejecución de flujo de trabajo. Por ejemplo, la matriz anterior creará los trabajos en el orden siguiente:
{version: 10, os: ubuntu-latest}{version: 10, os: windows-latest}{version: 12, os: ubuntu-latest}{version: 12, os: windows-latest}{version: 14, os: ubuntu-latest}{version: 14, os: windows-latest}
Una matriz puede generar un máximo de 256 trabajos por ejecución de flujo de trabajo. Este límite se aplica tanto a los ejecutores autohospedados como a los hospedados por GitHub Enterprise Cloud.
Las variables que defines se convierten en propiedades en el contexto de matrix y puedes hacer referencia a la propiedad en otras áreas del archivo de flujo de trabajo. En este ejemplo, puedes usar matrix.version y matrix.os para acceder al valor actual de version y os que el trabajo utiliza. Para obtener más información, vea «Acceso a información contextual sobre ejecuciones de flujo de trabajo».
Ejemplo: Uso de una matriz de una sola dimensión
Puedes especificar una variable para crear una matriz de una sola dimensión.
Por ejemplo, el flujo de trabajo siguiente define la variable version con los valores [10, 12, 14]. El flujo de trabajo ejecutará tres trabajos, uno para cada valor de la variable. Cada trabajo tendrá acceso al valor version mediante el contexto matrix.version y pasará el valor como node-version a la acción actions/setup-node.
jobs:
example_matrix:
strategy:
matrix:
version: [10, 12, 14]
steps:
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.version }}
Ejemplo: Uso de una matriz de varias dimensiones
Puedes especificar varias variables para crear una matriz multidimensional. Se ejecutará un trabajo para cada combinación posible de las variables.
Por ejemplo, el flujo de trabajo siguiente especifica dos variables:
- Dos sistemas operativos especificados en la variable
os - Tres versiones de Node.js especificadas en la variable
version
El flujo de trabajo ejecutará seis trabajos, uno para cada combinación de las variables os y version. Cada trabajo establecerá el valor runs-on en el valor os actual y pasará el valor version actual a la acción actions/setup-node.
jobs:
example_matrix:
strategy:
matrix:
os: [ubuntu-22.04, ubuntu-20.04]
version: [10, 12, 14]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.version }}
Una configuración de variable en una matriz puede ser array de object.
matrix:
os:
- ubuntu-latest
- macos-latest
node:
- version: 14
- version: 20
env: NODE_OPTIONS=--openssl-legacy-provider
Esta matriz genera 4 trabajos con los contextos correspondientes.
- matrix.os: ubuntu-latest
matrix.node.version: 14
- matrix.os: ubuntu-latest
matrix.node.version: 20
matrix.node.env: NODE_OPTIONS=--openssl-legacy-provider
- matrix.os: macos-latest
matrix.node.version: 14
- matrix.os: macos-latest
matrix.node.version: 20
matrix.node.env: NODE_OPTIONS=--openssl-legacy-provider
Ejemplo: Uso de contextos para crear matrices
Puedes usar contextos para crear matrices. Para obtener más información sobre los contextos, consulta "Acceso a información contextual sobre ejecuciones de flujo de trabajo".
Por ejemplo, el flujo de trabajo siguiente desencadena el evento repository_dispatch y usa información de la carga del evento para compilar la matriz. Cuando se crea un evento de distribución de repositorio con una carga como la siguiente, la variable de matriz version tendrá un valor de [12, 14, 16]. Para más información sobre el desencadenador repository_dispatch, consulta "Eventos que desencadenan flujos de trabajo".
{
"event_type": "test",
"client_payload": {
"versions": [12, 14, 16]
}
}
on:
repository_dispatch:
types:
- test
jobs:
example_matrix:
runs-on: ubuntu-latest
strategy:
matrix:
version: ${{ github.event.client_payload.versions }}
steps:
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.version }}
Expansión o incorporación de configuraciones de matriz
Usa jobs.<job_id>.strategy.matrix.include para expandir las configuraciones de matriz existentes o para agregar nuevas configuraciones. El valor de include es una lista de objetos.
Para cada objeto de la lista include, los pares clave:valor del objeto se agregarán a cada una de las combinaciones de matriz si ninguno de los pares clave:valor sobrescribe ninguno de los valores de matriz originales. Si el objeto no se puede agregar a ninguna de las combinaciones de matriz, se creará una nueva combinación de matriz. Ten en cuenta que los valores originales de matriz no se sobrescribirán, mientras que los valores agregados de matriz sí se pueden sobrescribir.
Por ejemplo, esta matriz:
strategy:
matrix:
fruit: [apple, pear]
animal: [cat, dog]
include:
- color: green
- color: pink
animal: cat
- fruit: apple
shape: circle
- fruit: banana
- fruit: banana
animal: cat
dará como resultado seis trabajos con las siguientes combinaciones de matriz:
{fruit: apple, animal: cat, color: pink, shape: circle}{fruit: apple, animal: dog, color: green, shape: circle}{fruit: pear, animal: cat, color: pink}{fruit: pear, animal: dog, color: green}{fruit: banana}{fruit: banana, animal: cat}
siguiendo esta lógica:
{color: green}se agrega a todas las combinaciones de matriz original, porque se puede agregar sin sobrescribir ninguna parte de las combinaciones originales.{color: pink, animal: cat}agregacolor:pinksolo a las combinaciones de matriz originales que incluyenanimal: cat. Esto sobrescribe elcolor: greenque ha sido agregado por la entrada anteriorinclude.{fruit: apple, shape: circle}agregashape: circlesolo a las combinaciones de matriz originales que incluyenfruit: apple.{fruit: banana}no se puede agregar a ninguna combinación de matriz original sin sobrescribir un valor, por lo que se agrega como una combinación de matriz adicional.{fruit: banana, animal: cat}no se puede agregar a ninguna combinación de matriz original sin sobrescribir un valor, por lo que se agrega como una combinación de matriz adicional. No se agrega a la combinación de matriz{fruit: banana}porque esa combinación no era una de las combinaciones de matriz original.
Ejemplo: Expansión de configuraciones
Por ejemplo, el siguiente flujo de trabajo ejecutará cuatro trabajos, uno para cada combinación de os y node. Cuando se ejecute el trabajo para el valor de os de windows-latest y el valor de node de 16, se incluirá en el trabajo una variable adicional denominada npm con el valor de 6.
jobs:
example_matrix:
strategy:
matrix:
os: [windows-latest, ubuntu-latest]
node: [14, 16]
include:
- os: windows-latest
node: 16
npm: 6
runs-on: ${{ matrix.os }}
steps:
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
- if: ${{ matrix.npm }}
run: npm install -g npm@${{ matrix.npm }}
- run: npm --version
Ejemplo: Incorporación de configuraciones
Por ejemplo, esta matriz ejecutará 10 trabajos, uno para cada combinación de os y version en la matriz, además de un trabajo para el valor os de windows-latest y el valor version de 17.
jobs:
example_matrix:
strategy:
matrix:
os: [macos-latest, windows-latest, ubuntu-latest]
version: [12, 14, 16]
include:
- os: windows-latest
version: 17
Si no especificas ninguna variable de matriz, se ejecutarán todas las configuraciones de include. Por ejemplo, el siguiente flujo de trabajo ejecutaría dos trabajos, uno para cada entrada include. Esto permite aprovechar la estrategia de matriz sin tener una matriz totalmente rellenada.
jobs:
includes_only:
runs-on: ubuntu-latest
strategy:
matrix:
include:
- site: "production"
datacenter: "site-a"
- site: "staging"
datacenter: "site-b"
Exclusión de configuraciones de matriz
Para quitar configuraciones específicas definidas en la matriz, usa jobs.<job_id>.strategy.matrix.exclude. Una configuración excluida solo debe ser una coincidencia parcial para que se excluya. Por ejemplo, el siguiente flujo de trabajo ejecutará nueve trabajos: un trabajo para cada una de las 12 configuraciones menos el trabajo excluido que coincide con {os: macos-latest, version: 12, environment: production} y los dos trabajos excluidos que coinciden con {os: windows-latest, version: 16}.
strategy:
matrix:
os: [macos-latest, windows-latest]
version: [12, 14, 16]
environment: [staging, production]
exclude:
- os: macos-latest
version: 12
environment: production
- os: windows-latest
version: 16
runs-on: ${{ matrix.os }}
Nota: Todas las combinaciones de include se procesan después de exclude. Esto le permite usar include para volver a agregar combinaciones previamente excluidas.
Ejemplo: Uso de una salida para definir dos matrices
Puede usar la salida de un trabajo para definir matrices para varios trabajos.
Por ejemplo, el flujo de trabajo siguiente muestra cómo definir una matriz de valores en un trabajo, usar esa matriz en un segundo trabajo para generar artefactos y, a continuación, consumir esos artefactos en un tercer trabajo. Cada artefacto está asociado a un valor de la matriz.
name: shared matrix
on:
push:
workflow_dispatch:
jobs:
define-matrix:
runs-on: ubuntu-latest
outputs:
colors: ${{ steps.colors.outputs.colors }}
steps:
- name: Define Colors
id: colors
run: |
echo 'colors=["red", "green", "blue"]' >> "$GITHUB_OUTPUT"
produce-artifacts:
runs-on: ubuntu-latest
needs: define-matrix
strategy:
matrix:
color: ${{ fromJSON(needs.define-matrix.outputs.colors) }}
steps:
- name: Define Color
env:
color: ${{ matrix.color }}
run: |
echo "$color" > color
- name: Produce Artifact
uses: actions/upload-artifact@v4
with:
name: ${{ matrix.color }}
path: color
consume-artifacts:
runs-on: ubuntu-latest
needs:
- define-matrix
- produce-artifacts
strategy:
matrix:
color: ${{ fromJSON(needs.define-matrix.outputs.colors) }}
steps:
- name: Retrieve Artifact
uses: actions/download-artifact@v4
with:
name: ${{ matrix.color }}
- name: Report Color
run: |
cat color
name: shared matrix
on:
push:
workflow_dispatch:
jobs:
define-matrix:
runs-on: ubuntu-latest
outputs:
colors: ${{ steps.colors.outputs.colors }}
steps:
- name: Define Colors
id: colors
run: |
echo 'colors=["red", "green", "blue"]' >> "$GITHUB_OUTPUT"
produce-artifacts:
runs-on: ubuntu-latest
needs: define-matrix
strategy:
matrix:
color: ${{ fromJSON(needs.define-matrix.outputs.colors) }}
steps:
- name: Define Color
env:
color: ${{ matrix.color }}
run: |
echo "$color" > color
- name: Produce Artifact
uses: actions/upload-artifact@v4
with:
name: ${{ matrix.color }}
path: color
consume-artifacts:
runs-on: ubuntu-latest
needs:
- define-matrix
- produce-artifacts
strategy:
matrix:
color: ${{ fromJSON(needs.define-matrix.outputs.colors) }}
steps:
- name: Retrieve Artifact
uses: actions/download-artifact@v4
with:
name: ${{ matrix.color }}
- name: Report Color
run: |
cat color
Administración de errores
Puedes controlar cómo se manejan los errores de trabajo con jobs.<job_id>.strategy.fail-fast y jobs.<job_id>.continue-on-error.
jobs.<job_id>.strategy.fail-fast se aplica a toda la matriz. Si jobs.<job_id>.strategy.fail-fast se establece en true o su expresión calcula hasta true, GitHub Enterprise Cloud cancelará todos los trabajos en curso y en cola en la matriz si se produce un error de cualquiera de los trabajos de esta. El valor predeterminado de esta propiedad es true.
jobs.<job_id>.continue-on-error se aplica a un solo trabajo. Si jobs.<job_id>.continue-on-error es true, el resto de los trabajos de la matriz seguirán ejecutándose aunque se produzca un error en el trabajo con jobs.<job_id>.continue-on-error: true.
Puede usar jobs.<job_id>.strategy.fail-fast y jobs.<job_id>.continue-on-error de forma conjunta. Por ejemplo, el flujo de trabajo siguiente iniciará cuatro trabajos. En cada trabajo, continue-on-error se determina mediante el valor de matrix.experimental. Si se produce un error en alguno de los trabajos con continue-on-error: false, se cancelarán todos los trabajos en curso o en la cola. Si se produce un error en el trabajo con continue-on-error: true, el resto de trabajos no se verán afectados.
jobs:
test:
runs-on: ubuntu-latest
continue-on-error: ${{ matrix.experimental }}
strategy:
fail-fast: true
matrix:
version: [6, 7, 8]
experimental: [false]
include:
- version: 9
experimental: true
Definición del número máximo de trabajos simultáneos
De forma predeterminada, GitHub Enterprise Cloud maximizará el número de trabajos ejecutados en paralelo en función de la disponibilidad del ejecutor. Para establecer el número máximo de trabajos que se pueden ejecutar simultáneamente al usar una estrategia de trabajo matrix, usa jobs.<job_id>.strategy.max-parallel.
Por ejemplo, el siguiente flujo de trabajo ejecutará un máximo de dos trabajos a la vez, incluso si hay ejecutores disponibles para ejecutar los seis trabajos a la vez.
jobs:
example_matrix:
strategy:
max-parallel: 2
matrix:
version: [10, 12, 14]
os: [ubuntu-latest, windows-latest]