Ejecución de variaciones de trabajos en un flujo de trabajo

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} agrega color:pink solo a las combinaciones de matriz originales que incluyen animal: cat. Esto sobrescribe el color: green que ha sido agregado por la entrada anterior include.
{fruit: apple, shape: circle} agrega shape: circle solo a las combinaciones de matriz originales que incluyen fruit: 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.

YAML

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]

Ejecución de variaciones de trabajos en un flujo de trabajo

En este artículo