행렬 전략 정보
매트릭스 전략을 사용하면 단일 작업 정의에서 변수를 사용하여 변수의 조합을 기반으로 하는 여러 작업 실행을 자동으로 만들 수 있습니다. 예를 들어 매트릭스 전략을 사용하여 여러 버전의 언어 또는 여러 운영 체제에서 코드를 테스트할 수 있습니다.
행렬 전략 사용
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 Enterprise Cloud은 실행기 가용성에 따라 병렬로 실행되는 작업 수를 최대화합니다. 행렬의 변수 순서에 따라 작업이 생성되는 순서가 결정됩니다. 정의한 첫 번째 변수는 워크플로 실행에서 만든 첫 번째 작업이 됩니다. 예를 들어 위의 행렬은 다음 순서로 작업을 만듭니다.
{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 Enterprise Cloud 호스팅 및 자체 호스팅 실행기 둘 다에 적용됩니다.
정의하는 변수는 matrix
컨텍스트의 속성이 되며 워크플로 파일의 다른 영역에서 속성을 참조할 수 있습니다. 이 예제에서는 matrix.version
및 matrix.os
를 사용하여 작업에서 사용 중인 version
및 os
의 현재 값에 액세스할 수 있습니다. 자세한 내용은 "워크플로 실행에 대한 컨텍스트 정보에 액세스"을(를) 참조하세요.
예시: 1차원 행렬 사용
단일 변수를 지정하여 단일 차원 행렬을 만들 수 있습니다.
예를 들어 다음 워크플로는 값 [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 }}
예시: 다차원 행렬 사용
여러 변수를 지정하여 다차원 매트릭스를 만들 수 있습니다. 가능한 각 변수 조합에 대해 작업이 실행됩니다.
예를 들어 다음 워크플로는 두 개의 변수를 지정합니다.
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
예시: 컨텍스트를 사용하여 행렬 만들기
컨텍스트를 사용하여 매트릭스를 만들 수 있습니다. 컨텍스트에 대한 자세한 내용은 "워크플로 실행에 대한 컨텍스트 정보에 액세스"를 참조하세요.
예를 들어 다음 워크플로는 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
값은 개체 목록입니다.
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}
행렬 조합은 원래 행렬 조합 중 하나가 아니었기 때문에 해당 조합에 추가하지 않습니다.
예시: 구성 확장
예를 들어, 다음 워크플로는 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
예시: 구성 추가
예를 들어 이 매트릭스는 매트릭스의 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"
행렬 구성 제외
매트릭스에 정의된 특정 구성을 제거하려면 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 }}
Note
모든 include
조합은 exclude
다음에 처리됩니다. include
를 사용하여 이전에 제외된 조합을 다시 추가하는 데 사용할 수 있습니다.
예시: 출력을 사용하여 두 행렬 정의
한 작업의 출력을 사용하여 여러 작업에 대한 행렬을 정의할 수 있습니다.
예를 들어 다음 워크플로는 한 작업에서 값 행렬을 정의하고, 두 번째 작업에서 해당 행렬을 사용하여 아티팩트를 생성한 다음, 세 번째 작업에서 해당 아티팩트를 사용하는 방법을 보여 줍니다. 각 아티팩트가 행렬의 값과 연결됩니다.
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>.strategy.fail-fast
가 true
로 설정되거나 식이 true
로 평가되면 GitHub Enterprise Cloud은(는) 행렬의 작업이 실패할 경우 행렬의 진행 중인 작업과 대기 중인 작업을 모두 취소합니다. 이 속성은 기본적으로 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
최대 동시 작업 수 정의
기본적으로 GitHub Enterprise Cloud은 실행기 가용성에 따라 병렬로 실행되는 작업 수를 최대화합니다. 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]