행렬 전략 정보
매트릭스 전략을 사용하면 단일 작업 정의에서 변수를 사용하여 변수의 조합을 기반으로 하는 여러 작업 실행을 자동으로 만들 수 있습니다. 예를 들어 매트릭스 전략을 사용하여 여러 버전의 언어 또는 여러 운영 체제에서 코드를 테스트할 수 있습니다.
워크플로 작업에 매트릭스 전략 추가
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에 대한 워크플로 구문을(를) 참조하세요.
출력을 사용하여 두 매트릭스 정의
한 작업의 출력을 사용하여 여러 작업에 대한 행렬을 정의할 수 있습니다.
예를 들어 다음 워크플로는 한 작업에서 값 행렬을 정의하고, 두 번째 작업에서 해당 행렬을 사용하여 아티팩트를 생성한 다음, 세 번째 작업에서 해당 아티팩트를 사용하는 방법을 보여 줍니다. 각 아티팩트가 행렬의 값과 연결됩니다.
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
오류 처리
작업 오류를 처리하는 방법을 제어하려면 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에 대한 워크플로 구문을(를) 참조하세요.