매트릭스 전략 (Matrix)

"같은 테스트를 여러 OS·여러 버전에서 돌리고 싶다"는 요구는 CI에서 아주 흔해요. 매트릭스 전략(Matrix Strategy)은 잡 정의 하나에 변수 목록을 선언해 두면, 그 변수들의 모든 조합으로 잡을 자동 생성해 주는 기능이에요. 한 워크플로 안에서 반복 YAML을 줄이고 넓은 호환성을 검증하고 싶을 때 특히 유용해요.

상위 문서: GitHub Actions · 잡 · 워크플로 문법

출처: https://docs.github.com/actions/using-jobs/using-a-matrix-for-your-jobs

매트릭스 선언하기

jobs.<job_id>.strategy.matrix 아래에 변수 하나와 값 배열을 적어요. 예를 들어 버전 변수 version: [10, 12, 14]와 OS 변수 os: [ubuntu-latest, windows-latest]를 선언하면, 3×2 = 6개의 조합, 즉 잡 6개가 생겨요.

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

각 조합마다 잡이 하나씩 도니까, 실행 OS·버전을 runs-on: ${{ matrix.os }}처럼 매트릭스 변수로 참조해서 사용해요. 잡 안에서는 <매트릭스 변수> 값을 컨텍스트처럼 꺼내 써요.

컨텍스트로 매트릭스 만들기

매트릭스 변수에 이벤트 페이로드 등 컨텍스트 값을 넣을 수도 있어요. 예를 들어 repository_dispatch가 날아온 페이로드의 버전 목록을 그대로 매트릭스로 쓰는 식이에요.

on:
  repository_dispatch:
    types:
      - test

jobs:
  example_matrix:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        version: ${{ github.event.client_payload.versions }}

이렇게 하면 외부에서 트리거할 때마다 페이로드에 따라 테스트 버전이 달라져요.

조합 추가·제외하기

include:로 매트릭스에 추가 조합을 얹고, exclude:로 특정 조합을 빼서 실행 횟수를 조절할 수 있어요.

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

위 예시에서는 12개 조합 중 제외된 3개를 뺀 9개 잡이 생성돼요. 어떤 조합을 빼야 하는지 직관적으로 명시할 수 있어서, "이 조합은 이미 검증됐다" 같은 규칙을 코드로 관리하기 좋아요.

실패 처리 — fail-fast · continue-on-error

매트릭스 전체의 실패 정책은 jobs.<job_id>.strategy.fail-fast, 개별 잡의 실패 정책은 jobs.<job_id>.continue-on-error로 나눠요.

fail-fast: true (기본) — 매트릭스 중 하나라도 실패하면 진행 중·대기 중인 나머지 잡을 모두 취소해요.
continue-on-error: true — 이 잡이 실패해도 다른 잡은 계속 돌게 해요. 실험적인 버전(experimental)을 섞어 테스트할 때 유용해요.

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

continue-on-error: false인 잡이 실패하면 나머지를 취소하고, true인 잡이 실패하면 다른 잡은 그대로 계속돼요.

동시 실행 개수 제한 — max-parallel

jobs.<job_id>.strategy.max-parallel로 한 번에 동시에 돌 잡의 최대 개수를 정해요. 러너가 6개 다 돌릴 수 있어도 max-parallel: 2로 두면 한 번에 2개씩만 돌아가요.

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

매트릭스 변수에 컨텍스트를 넣으면 페이로드에 따라 실행 조합을 동적으로 바꿀 수 있지만, 한 워크플로 실행당 최대 256개 잡이라는 상한은 GitHub 호스팅 러너와 셀프 호스팅 러너 모두에 적용된다는 점을 꼭 기억해요.

매트릭스 전략 (Matrix)