Using a matrix for your jobs

About matrix strategies

A matrix strategy lets you use variables in a single job definition to automatically create multiple job runs that are based the combinations of the variables. For example, you can use a matrix strategy to test your code in multiple versions of a language or on multiple operating systems.

Using a matrix strategy

Utiliza jobs.<job_id>.strategy.matrix para definir una matriz de configuraciones de jobs diferentes. Within your matrix, define one or more variables followed by an array of values. For example, the following matrix has a variable called version with the value [10, 12, 14] and a variable called os with the value [ubuntu-latest, windows-latest]:

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

A job will run for each possible combination of the variables. In this example, the workflow will run six jobs, one for each combination of the os and version variables.

By default, GitHub Enterprise Server will maximize the number of jobs run in parallel depending on runner availability. The order of the variables in the matrix determines the order in which the jobs are created. The first variable you define will be the first job that is created in your workflow run. For example, the above matrix will create the jobs in the following order:

• {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}

A matrix will generate a maximum of 256 jobs per workflow run. Este límite aplica tanto a los ejecutores hospedados en GitHub Enterprise Server como a los auto-hospedados.

The variables that you define become properties in the matrix context, and you can reference the property in other areas of your workflow file. In this example, you can use matrix.version and matrix.os to access the current value of version and os that the job is using. Para obtener más información, consulta "Contextos".

Example: Using a single-dimension matrix

You can specify a single variable to create a single-dimension matrix.

For example, the following workflow defines the variable version with the values [10, 12, 14]. The workflow will run three jobs, one for each value in the variable. Each job will access the version value through the matrix.version context and pass the value as node-version to the actions/setup-node action.

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
    steps:
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.version }}

Example: Using a multi-dimension matrix

You can specify multiple variables to create a multi-dimensional matrix. Un job se ejecutará para cada combinación posible de las variables.

For example, the following workflow specifies two variables:

• Two operating systems specified in the os variable
• Three Node.js versions specified in the version variable

The workflow will run six jobs, one for each combination of the os and version variables. Each job will set the runs-on value to the current os value and will pass the current version value to the actions/setup-node action.

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [ubuntu-18.04, ubuntu-20.04]
        version: [10, 12, 14]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.version }}

Example: Using contexts to create matrices

You can use contexts to create matrices. Para obtener más información sobre los contextos, consulta la sección "Contextos".

For example, the following workflow triggers on the repository_dispatch event and uses information from the event payload to build the matrix. When a repository dispatch event is created with a payload like the one below, the matrix version variable will have a value of [12, 14, 16]. For more information about the repository_dispatch trigger, see "Events that trigger workflows."

{
  "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@v2
        with:
          node-version: ${{ matrix.version }}

Expanding or adding matrix configurations

Use jobs.<job_id>.strategy.matrix.include to expand existing matrix configurations or to add new configurations. The value of include is a list of objects.

For each object in the include list, the key:value pairs in the object will be added to each of the matrix combinations if none of the key:value pairs overwrite any of the original matrix values. If the object cannot be added to any of the matrix combinations, a new matrix combination will be created instead. Note that the original matrix values will not be overwritten, but added matrix values can be overwritten.

For example, this matrix:

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

will result in six jobs with the following matrix combinations:

• {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}

following this logic:

• {color: green} is added to all of the original matrix combinations because it can be added without overwriting any part of the original combinations.
• {color: pink, animal: cat} adds color:pink only to the original matrix combinations that include animal: cat. This overwrites the color: green that was added by the previous include entry.
• {fruit: apple, shape: circle} adds shape: circle only to the original matrix combinations that include fruit: apple.
• {fruit: banana} cannot be added to any original matrix combination without overwriting a value, so it is added as an additional matrix combination.
• {fruit: banana, animal: cat} cannot be added to any original matrix combination without overwriting a value, so it is added as an additional matrix combination. It does not add to the {fruit: banana} matrix combination because that combination was not one of the original matrix combinations.

Example: Expanding configurations

For example, the following workflow will run six jobs, one for each combination of os and node. When the job for the os value of windows-latest and node value of 16 runs, an additional variable called npm with the value of 6 will be included in the job.

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest]
        node: [12, 14, 16]
        include:
          - os: windows-latest
            node: 16
            npm: 6
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node }}
      - if: ${{ matrix.npm }}
        run: npm install -g npm@${{ matrix.npm }}
      - run: npm --version

Example: Adding configurations

For example, this matrix will run 10 jobs, one for each combination of os and version in the matrix, plus a job for the os value of windows-latest and version value of 17.

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
        version: [12, 14, 16]
        include:
          - os: windows-latest
            version: 17

If you don't specify any matrix variables, all configurations under include will run. For example, the following workflow would run two jobs, one for each include entry. This lets you take advantage of the matrix strategy without having a fully populated matrix.

jobs:
  includes_only:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - site: "production"
            datacenter: "site-a"
          - site: "staging"
            datacenter: "site-b"

Excluding matrix configurations

To remove specific configurations defined in the matrix, use jobs.<job_id>.strategy.matrix.exclude. An excluded configuration only has to be a partial match for it to be excluded. For example, the following workflow will run nine jobs: one job for each of the 12 configurations, minus the one excluded job that matches {os: macos-latest, version: 12, environment: production}, and the two excluded jobs that match {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 }}

Handling failures

Puedes controlar cómo se manejan los fallos de los jobs con jobs.<job_id>.strategy.fail-fast y jobs.<job_id>.continue-on-error.

jobs.<job_id>.strategy.fail-fast aplica a toda la matriz. Si configuras a jobs.<job_id>.strategy.fail-fast como true, GitHub Enterprise Server cancelará todos los jobs de la matriz que estén en cola y en progreso en caos de que cualquiera de ellos falle. Esta propiedad se predetermina en true.

jobs.<job_id>.continue-on-error aplica a un solo job. Si jobs.<job_id>.continue-on-error es true, otros jobs en la matriz seguirán ejecutándose, incluso si el job con jobs.<job_id>.continue-on-error: true falla.

Puedes utilizar jobs.<job_id>.strategy.fail-fast y jobs.<job_id>.continue-on-error juntos. Por ejemplo, el siguiente flujo de trabajo iniciará cuatro jobs. Para cada job, continue-on-error se determina mediante el valor de matrix.experimental. Si cualquiera de los jobs con continue-on-error: false falla, todos los jobs que estén en progreso o en cola se cancelarán. Si el job con continue-on-error: true falla, los otros 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

Defining the maximum number of concurrent jobs

By default, GitHub Enterprise Server will maximize the number of jobs run in parallel depending on runner availability. Para configurar la cantidad máxima de jobs que puedan ejecutarse simultáneamente al utilizar una estrategia de jobs de matrix, utiliza jobs.<job_id>.strategy.max-parallel.

Por ejemplo, el siguiente flujo de trabajo ejecutará un máximo de dos jobs a la vez, incluso si hay ejecutores disponibles para ejecutar los seis jobs al mismo tiempo.

jobs:
  example_matrix:
    strategy:
      max-parallel: 2
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]