Running variations of jobs in a workflow

About matrix strategies

매트릭스 전략을 사용하면 단일 작업 정의에서 변수를 사용하여 변수의 조합을 기반으로 하는 여러 작업 실행을 자동으로 만들 수 있습니다. 예를 들어 매트릭스 전략을 사용하여 여러 버전의 언어 또는 여러 운영 체제에서 코드를 테스트할 수 있습니다.

Using a matrix strategy

jobs.<job_id>.strategy.matrix를 사용하여 다양한 작업 구성 행렬을 정의합니다. 행렬 내에서 하나 이상의 변수와 값 배열을 정의합니다. 예를 들어 다음 행렬에는 값 [10, 12, 14]의 version 변수와 값 [ubuntu-latest, windows-latest]의 os 변수가 있습니다.

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

가능한 각 변수 조합에 대해 작업이 실행됩니다. 이 예제에서 워크플로는 os 및 version 변수의 각 조합에 대해 하나씩 6개의 작업을 실행합니다.

기본적으로 GitHub은 실행기 가용성에 따라 병렬로 실행되는 작업 수를 최대화합니다. 행렬의 변수 순서에 따라 작업이 생성되는 순서가 결정됩니다. 정의한 첫 번째 변수는 워크플로 실행에서 만든 첫 번째 작업이 됩니다. 예를 들어 위의 행렬은 다음 순서로 작업을 만듭니다.

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

행렬은 워크플로 실행당 최대 256개의 작업을 생성합니다. 이러한 제한은 GitHub 호스팅 및 자체 호스팅 실행기 둘 다에 적용됩니다.

정의하는 변수는 matrix 컨텍스트의 속성이 되며 워크플로 파일의 다른 영역에서 속성을 참조할 수 있습니다. 이 예제에서는 matrix.version 및 matrix.os를 사용하여 작업에서 사용 중인 version 및 os의 현재 값에 액세스할 수 있습니다. 자세한 내용은 "Accessing contextual information about workflow runs"을(를) 참조하세요.

Example: Using a single-dimension matrix

단일 변수를 지정하여 단일 차원 행렬을 만들 수 있습니다.

예를 들어 다음 워크플로는 값 [10, 12, 14]를 사용하여 변수 version을 정의합니다. 워크플로는 변수의 각 값에 대해 하나씩 3개의 작업을 실행합니다. 각 작업은 matrix.version 컨텍스트를 통해 version 값에 액세스하고 해당 값을 actions/setup-node 작업에 node-version으로 전달합니다.

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

Example: Using a multi-dimension matrix

여러 변수를 지정하여 다차원 매트릭스를 만들 수 있습니다. 가능한 각 변수 조합에 대해 작업이 실행됩니다.

예를 들어 다음 워크플로는 두 개의 변수를 지정합니다.

• os 변수에 지정된 운영 체제 2개
• version 변수에 지정된 Node.js 버전 3개

워크플로는 os 및 version 변수의 각 조합에 대해 하나씩 6개의 작업을 실행합니다. 각 작업은 runs-on 값을 현재 os 값으로 설정하고 현재 version 값을 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 }}

매트릭스의 변수 구성은 object의 array일 수 있습니다.

matrix:
  os:
    - ubuntu-latest
    - macos-latest
  node:
    - version: 14
    - version: 20
      env: NODE_OPTIONS=--openssl-legacy-provider

이 매트릭스는 해당 컨텍스트를 사용하여 4개의 작업을 생성합니다.

- 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

Example: Using contexts to create matrices

컨텍스트를 사용하여 매트릭스를 만들 수 있습니다. 컨텍스트에 대한 자세한 내용은 "Accessing contextual information about workflow runs"를 참조하세요.

예를 들어 다음 워크플로는 repository_dispatch 이벤트에서 트리거하고 이벤트 페이로드의 정보를 사용하여 매트릭스를 빌드합니다. 아래와 같은 페이로드를 사용하여 리포지토리 디스패치 이벤트를 만들면 매트릭스 version 변수가 [12, 14, 16] 값을 갖습니다. repository_dispatch 트리거에 대한 자세한 내용은 "워크플로를 트리거하는 이벤트"을 참조하세요.

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

Expanding or adding matrix configurations

jobs.<job_id>.strategy.matrix.include를 사용하여 기존 행렬 구성을 확장하거나 새 구성을 추가합니다. include 값은 개체 목록입니다.

include 목록의 각 개체에서 키:값 쌍이 원래 행렬 값을 덮어쓰지 않으면 개체의 키:값 쌍이 각 행렬 조합에 추가됩니다. 개체를 행렬 조합에 추가할 수 없는 경우 대신 새 행렬 조합이 만들어집니다. 원래 행렬 값은 덮어쓰는 것이 아니라 추가된 행렬 값을 덮어쓸 수 있습니다.

예를 들어, 이 행렬은

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

다음 행렬 조합을 사용하여 6개 작업을 생성합니다.

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

이때 다음 논리를 따릅니다.

• {color: green}는 원래 조합의 일부를 덮어쓰지 않고 추가될 수 있으므로 모든 원래 행렬 조합에 추가됩니다.
• {color: pink, animal: cat}는 animal: cat을 포함하는 원래 행렬 조합에만 color:pink을 추가합니다. 이렇게 하면 이전 include 항목이 추가한 color: green을 덮어씁니다.
• {fruit: apple, shape: circle}는 fruit: apple을 포함하는 원래 행렬 조합에만 shape: circle을 추가합니다.
• {fruit: banana}는 값을 덮어쓰지 않고는 원래 행렬 조합에 추가될 수 없으므로 추가 행렬 조합으로 추가됩니다.
• {fruit: banana, animal: cat}는 값을 덮어쓰지 않고는 원래 행렬 조합에 추가될 수 없으므로 추가 행렬 조합으로 추가됩니다. {fruit: banana} 행렬 조합은 원래 행렬 조합 중 하나가 아니었기 때문에 해당 조합에 추가하지 않습니다.

Example: Expanding configurations

예를 들어, 다음 워크플로는 os 및 node의 각 조합에 대해 하나씩 4개의 작업을 실행합니다. windows-latest의 os 값과 16의 node 값에 대한 작업이 실행되면 6 값을 사용하는 npm이라는 추가 변수가 작업에 포함됩니다.

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

Example: Adding configurations

예를 들어 이 매트릭스는 매트릭스의 os 및 version 각 조합에 대해 하나씩 10개의 작업과 windows-latest의 os 값과 17의 version 값에 대한 작업을 실행합니다.

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

매트릭스 변수를 지정하지 않으면 include 아래의 모든 구성이 실행됩니다. 예를 들어 다음 워크플로는 각 include 항목에 대해 하나씩 두 개의 작업을 실행합니다. 이렇게 하면 완전히 채워진 매트릭스 없이 매트릭스 전략을 활용할 수 있습니다.

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

Excluding matrix configurations

매트릭스에 정의된 특정 구성을 제거하려면 jobs.<job_id>.strategy.matrix.exclude를 사용합니다. 제외된 구성은 제외되려면 부분 일치여야 합니다. 예를 들어 다음 워크플로는 9개의 작업을 실행합니다. 12개 구성 각각에 대해 하나의 작업에서 {os: macos-latest, version: 12, environment: production}과 일치하는 제외된 작업 하나와 {os: windows-latest, version: 16}과 일치하는 제외된 작업 2개를 뺀 값입니다.

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

Example: Using an output to define two matrices

한 작업의 출력을 사용하여 여러 작업에 대한 행렬을 정의할 수 있습니다.

예를 들어 다음 워크플로는 한 작업에서 값 행렬을 정의하고, 두 번째 작업에서 해당 행렬을 사용하여 아티팩트를 생성한 다음, 세 번째 작업에서 해당 아티팩트를 사용하는 방법을 보여 줍니다. 각 아티팩트가 행렬의 값과 연결됩니다.

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

Handling failures

jobs.<job_id>.strategy.fail-fast 및 jobs.<job_id>.continue-on-error로 작업 오류를 처리하는 방법을 제어할 수 있습니다.

jobs.<job_id>.strategy.fail-fast는 전체 행렬에 적용됩니다. jobs.<job_id>.strategy.fail-fast가 true로 설정되거나 식이 true로 평가되면 GitHub은(는) 행렬의 작업이 실패할 경우 행렬의 진행 중인 작업과 대기 중인 작업을 모두 취소합니다. 이 속성은 기본적으로 true입니다.

jobs.<job_id>.continue-on-error는 단일 작업에 적용됩니다. jobs.<job_id>.continue-on-error가 true인 경우 jobs.<job_id>.continue-on-error: true인 작업이 실패하더라도 행렬의 다른 작업은 계속 실행됩니다.

jobs.<job_id>.strategy.fail-fast 및 jobs.<job_id>.continue-on-error를 함께 사용할 수 있습니다. 예를 들어 다음 워크플로는 4개의 작업을 시작합니다. 각 작업에 대해 continue-on-error는 matrix.experimental 값으로 결정됩니다. continue-on-error: false인 작업이 실패하면 진행 중이거나 큐에 대기 중인 모든 작업이 취소됩니다. continue-on-error: true인 작업이 실패하면 다른 작업은 영향을 받지 않습니다.

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

기본적으로 GitHub은 실행기 가용성에 따라 병렬로 실행되는 작업 수를 최대화합니다. matrix 작업 전략을 사용할 때 동시에 실행할 수 있는 최대 작업 수를 설정하려면 jobs.<job_id>.strategy.max-parallel을 사용하세요.

예를 들어 다음 워크플로는 한 번에 6개의 작업을 모두 실행할 수 있는 실행자가 있더라도 한 번에 최대 두 개의 작업만 실행합니다.

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