워크플로에서 작업 변형 실행

각 작업에 대한 변형을 정의하는 행렬을 만듭니다.

이 문서의 내용

행렬 전략 정보

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

워크플로 작업에 매트릭스 전략 추가

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개의 작업을 실행합니다.

예를 들어 위의 매트릭스는 다음 순서로 작업을 만듭니다.

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

참조 정보 및 예제는 GitHub Actions에 대한 워크플로 구문을(를) 참조하세요.

컨텍스트를 사용하여 매트릭스 만들기

워크플로 실행, 변수, 실행기 환경, 작업, 단계에 대한 정보를 사용하여 매트릭스를 만들려면 ${{ <context> }} 식 구문을 사용하여 컨텍스트에 액세스합니다. 컨텍스트에 대한 자세한 내용은 컨텍스트 참조을(를) 참조하세요.

예를 들어 다음 워크플로는 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 }}

행렬 구성 확장 또는 추가

jobs.<job_id>.strategy.matrix.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}

각 include 항목은 다음과 같은 방법으로 적용되었습니다.

  • {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} 행렬 조합은 원래 행렬 조합 중 하나가 아니었기 때문에 해당 조합에 추가하지 않습니다.

참조 및 예제 구성은 GitHub Actions에 대한 워크플로 구문을(를) 참조하세요.

행렬 구성 제외

매트릭스에 정의된 특정 구성을 제거하려면 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 }}

참조 정보는 GitHub Actions에 대한 워크플로 구문을(를) 참조하세요.

출력을 사용하여 두 매트릭스 정의

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

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

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@v5
      with:
        name: ${{ matrix.color }}

    - name: Report Color
      run: |
        cat color

오류 처리

작업 오류를 처리하는 방법을 제어하려면 jobs.<job_id>.strategy.fail-fast 및 jobs.<job_id>.continue-on-error를 사용하세요.

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

참조 정보는 jobs.<job_id>.strategy.fail-fast 및 jobs.<job_id>.continue-on-error를 참조하세요.

최대 동시 작업 수 정의

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]

참조 정보는 GitHub Actions에 대한 워크플로 구문을(를) 참조하세요.