Skip to main content
Publicamos atualizações frequentes em nossa documentação, e a tradução desta página ainda pode estar em andamento. Para obter as informações mais recentes, acesse a documentação em inglês. Se houver problemas com a tradução desta página, entre em contato conosco.
O GitHub AE está atualmente sob versão limitada. Entre em contato com nossa Equipe de Vendas para saber mais.

Usando uma matriz para seus trabalhos

Crie uma matriz para definir variações para cada trabalho.

Sobre estratégias da matriz

Uma estratégia de matriz permite usar variáveis em uma única definição de trabalho para criar automaticamente várias execuções de trabalho que são baseadas nas combinações das variáveis. Por exemplo, você pode usar uma estratégia de matriz para testar seu código em várias versões de uma linguagem ou em vários sistemas operacionais.

Usando uma estratégia da matriz

Use jobs.<job_id>.strategy.matrix para definir uma matriz de diferentes configurações de trabalho. 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 AE 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. This limit applies to both GitHub AE-hosted and self-hosted runners.

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 obter mais informações, consulte "Contextos".

Exemplo: Usando uma matriz de dimensão única

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

Exemplo: Usando uma matriz de múltiplas dimensões

Você pode especificar diversas variáveis para criar uma matriz multidimensional. A job will run for each possible combination of the variables.

Por exemplo, o fluxo de trabalho a seguir especifica duas variáveis:

  • Dois sistemas operacionais especificados na variável os
  • Três versões do Node.js especificadas na variável versão

O fluxo de trabalho irá executar seis trabalhos, um para cada combinação das variáveis os e versão. Cada trabalho irá definir o valor runs-on para o valor atual de os e vai passar o valor atual de versão para a ação actions/setup-node.

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

Exemplo: Usando contextos para criar matrizes

Você pode usar contextos para criar matrizes. Para obter mais informações sobre os contextos, consulte "Contextos".

Por exemplo, os seguintes gatilhos de fluxo de trabalho no evento repository_dispatch e usa informações da carga do evento para criar a matriz. Quando um evento de envio de repositório é criado com uma carga como a abaixo, a variável versão da matriz terá um valor de [12, 14, 16]. Para obter mais informações sobre o gatilho repository_dispatch, consulte "Eventos que acionam fluxos de trabalho".

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

Expansão ou adição de configurações da matriz

Use jobs.<job_id>.strategy.matrix.include para expandir as configurações da matriz existentes ou para adicionar novas configurações. O valor de incluir é uma lista de objetos.

Para cada objeto na lista incluir, os pares chave-valor no objeto serão adicionados a cada uma das combinações da matriz se nenhum dos pares chave-valor sobrescrever qualquer dos valores originais da matriz. Se o objeto não pode ser adicionado a qualquer das combinações matriz, será criada uma nova combinação matriz. Observe que os valores originais da matriz não serão substituídos, mas valores adicionados da matriz podem ser substituídos.

Por exemplo, 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

resultará em seis trabalhos com as seguintes combinações 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}

seguindo esta lógica:

  • {color: green} é adicionado a todas as combinações de matrizes originais, porque pode ser adicionado sem substituir nenhuma parte das combinações originais.
  • {color: pink, animal: cat} adiciona color>pink apenas para as combinações originais da matriz que incluem 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.

Exemplo: Expandir configurações

Por exemplo, o fluxo de trabalho a seguir irá executar seis trabalhos, um para cada combinação de os e node. Quando o valor do trabalho para o os de windows-latest e o valor node de 16 for executado, uma variável adicional chamada npm com o valor de 6 será incluída no trabalho.

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

Exemplo: Adicionar configurações

Por exemplo, esta matriz gerará 10 trabalhos, um para cada combinação de os e versão na matriz, mais um trabalho para o valor de os de windows-latest e o valor da versão de 17.

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

Se você não especificar nenhuma variável da matriz, todas as configurações em incluir serão executadas. Por exemplo, o seguinte fluxo de trabalho executaria dois trabalhos, um para cada entrada de incluir. Isso permite que você aproveite a estratégia da matriz sem ter uma matriz totalmente preenchida.

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

Excluindo configurações de matriz

Para remover configurações específicas definidas na matriz, use jobs.<job_id>.strategy.matrix.exclude. Uma configuração excluída só precisa ser uma correspondência parcial para que seja excluída. Por exemplo, o fluxo de trabalho a seguir irá executar nove trabalhos: um trabalho para cada uma das 12 configurações, menos a tarefa excluída que corresponde a {os: macos-latest, version: 12, environment: production}, e os dois trabalhos excluídos que correspondem a {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 }}

Observação: Todas as combinações de incluir são processadas depois de excluir. Isso permite que você use incluir para voltar a adicionar combinações que foram excluídas anteriormente.

Gerenciando as falhas

Você pode controlar como falhas de trabalho são tratadas com jobs.<job_id>.strategy.fail-fast e jobs.<job_id>.continue-on-error.

jobs.<job_id>.strategy.fail-fast aplica-se à matriz inteira. Se jobs.<job_id>.strategy.fail-fast estiver definido como verdadeiro, GitHub AE cancelará todos os trabalhos em andamento e agendados na matriz se algum trabalho na matriz falhar. This property defaults to true.

jobs.<job_id>.continue-on-error applies to a single job. If jobs.<job_id>.continue-on-error is true, other jobs in the matrix will continue running even if the job with jobs.<job_id>.continue-on-error: true fails.

You can use jobs.<job_id>.strategy.fail-fast and jobs.<job_id>.continue-on-error together. For example, the following workflow will start four jobs. For each job, continue-on-error is determined by the value of matrix.experimental. If any of the jobs with continue-on-error: false fail, all jobs that are in progress or queued will be cancelled. If the job with continue-on-error: true fails, the other jobs will not be affected.

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

Definindo o número máximo de trabalhos simultâneos

By default, GitHub AE will maximize the number of jobs run in parallel depending on runner availability. Para definir o número máximo de trabalhos que podem ser executados simultaneamente ao usar uma estratégia de trabalho de matriz, use jobs.<job_id>.strategy.max-parallel.

Por exemplo, o fluxo de trabalho seguinte será executado um máximo de duas tarefas por vez, mesmo que haja executores disponíveis para executar todos os seis trabalhos de uma só vez.

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