GitHub Actions 매트릭스 빌드 - 병렬 테스트 자동화

소개

소프트웨어를 개발할 때, 코드가 다양한 환경에서 올바르게 작동하는지 확인하는 것이 매우 중요합니다. 예를 들어, Node.js 라이브러리는 여러 버전의 Node.js(예: v18, v20, v22) 에서 테스트되어야 합니다.

각 버전에 대해 별도의 작업을 생성하는 대신, GitHub Actions 는 **매트릭스 전략 (Matrix Strategy)**을 제공합니다. 이를 통해 변수 집합을 정의할 수 있으며, GitHub Actions 는 이러한 변수의 모든 조합에 대해 자동으로 작업을 생성합니다.

이 실습에서는 워크플로우를 업데이트하여 세 가지 다른 버전의 Node.js 에서 테스트를 병렬로 실행하게 됩니다.

이 실습은 이전 실습에서 생성한 리포지토리를 기반으로 합니다. github-actions-demo 리포지토리에서 작업하게 됩니다.

전략 행렬 (Strategy Matrix) 을 포함하도록 워크플로 수정

strategy 키워드는 빌드 행렬 (build matrix) 을 구성하는 데 사용됩니다. 여기서는 단일 키 node-version을 가진 행렬을 정의할 것입니다.

github-actions-demo의 GitHub 저장소 페이지에서 녹색 Code 버튼을 클릭합니다.
HTTPS 탭이 선택되었는지 확인하고 URL 을 복사합니다. URL 은 https://github.com/your-username/github-actions-demo.git과 유사해야 합니다.
LabEx 환경에서 터미널을 엽니다. 기본 경로는 ~/project입니다.
git clone 명령어를 사용하여 저장소를 다운로드합니다. your-username을 실제 GitHub 사용자 이름으로 바꾸십시오.

cd ~/project
git clone https://github.com/your-username/github-actions-demo.git

예시 출력:

Cloning into 'github-actions-demo'...
remote: Enumerating objects: X, done.
remote: Counting objects: 100% (X/X), done.
remote: Total X (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (X/X), done.

클론된 저장소 디렉토리로 이동합니다:

cd ~/project/github-actions-demo

WebIDE 편집기를 사용하여 새 워크플로우 파일 .github/workflows/matrix-build.yml을 생성합니다. 이 파일은 왼쪽 파일 탐색기에서 project/github-actions-demo/.github/workflows/ 아래에서 찾을 수 있습니다.
기본 워크플로우 구조를 생성하는 것으로 시작합니다. 워크플로우 이름과 트리거를 추가합니다:

name: Matrix Build

on: [push]

기본 빌드 작업 구조를 가진 jobs 섹션을 추가합니다:

jobs:
  build:
    runs-on: ubuntu-latest

행렬 전략을 추가합니다. 이것이 여러 Node.js 버전을 사용하여 작업을 실행할 수 있게 하는 핵심 부분입니다:

strategy:
  matrix:
    node-version: [18, 20, 22]

이는 세 가지 값을 가진 node-version이라는 행렬 변수를 정의합니다. GitHub Actions 는 각 값에 대해 별도의 작업을 생성합니다.

steps 섹션을 추가합니다. 먼저, 체크아웃 단계를 추가합니다:

steps:
  - uses: actions/checkout@v4

Node.js 설정 단계를 추가합니다. 현재 행렬 값을 참조하기 위해 ${{ matrix.node-version }}을 사용하는 방식에 주목하십시오:

- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: ${{ matrix.node-version }}

종속성을 설치하는 단계를 추가합니다:

- name: Install dependencies
  run: npm install

아티팩트 디렉토리를 생성하는 빌드 단계를 추가합니다:

- name: Build project
  run: |
    mkdir dist
    echo "This is the build artifact" > dist/build.txt

테스트 단계를 추가합니다:

- name: Run tests
  run: npm test

마지막으로, 빌드 아티팩트 업로드 단계를 추가합니다. 각 아티팩트를 고유하게 만들기 위해 아티팩트 이름에 행렬 버전이 포함되는 방식에 주목하십시오:

- name: Upload build artifact
  uses: actions/upload-artifact@v4
  with:
    name: build-assets-${{ matrix.node-version }}
    path: dist

이제 전체 파일은 다음과 같이 보일 것입니다:

name: Matrix Build

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [18, 20, 22]

    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - name: Install dependencies
        run: npm install
      - name: Build project
        run: |
          mkdir dist
          echo "This is the build artifact" > dist/build.txt
      - name: Run tests
        run: npm test
      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          name: build-assets-${{ matrix.node-version }}
          path: dist

설명 (Explanation)

strategy: 빌드 전략을 정의합니다.
matrix: 행렬 변수들을 정의합니다.
node-version: 우리가 선택한 변수 이름입니다. 여기에 값의 배열 [18, 20, 22]을 할당했습니다. GitHub Actions 는 build 작업을 각 값에 대해 세 번 실행합니다.
${{ matrix.node-version }}: 이 구문은 단계 (step) 내에서 현재 행렬 값에 접근할 수 있게 해줍니다.

변경 사항을 저장하십시오 (Ctrl+S 또는 Cmd+S).

setup-node 및 아티팩트 이름에 행렬 컨텍스트 (matrix context) 사용하도록 업데이트

매트릭스를 정의하는 것은 절반의 성공일 뿐이며, 각 단계가 매트릭스에서 현재 값을 사용하도록 지시해야 합니다. 이는 ${{ matrix.node-version }} 컨텍스트를 사용하여 수행합니다.

또한 각 병렬 작업 (parallel job) 이 업로드하는 아티팩트 (artifact) 의 이름이 고유하도록 보장해야 합니다. 그렇지 않으면 서로 덮어쓰게 됩니다.

.github/workflows/matrix-build.yml 파일에서 Use Node.js 단계가 매트릭스 변수를 사용하는지 확인합니다:

- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: ${{ matrix.node-version }}

Upload build artifact 단계가 아티팩트 이름에 매트릭스 버전을 포함하는지 확인합니다:

- name: Upload build artifact
  uses: actions/upload-artifact@v4
  with:
    name: build-assets-${{ matrix.node-version }}
    path: dist

완성된 워크플로우 파일은 다음과 같아야 합니다:

name: Matrix Build

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [18, 20, 22]

    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - name: Install dependencies
        run: npm install
      - name: Build project
        run: |
          mkdir dist
          echo "This is the build artifact" > dist/build.txt
      - name: Run tests
        run: npm test
      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          name: build-assets-${{ matrix.node-version }}
          path: dist

파일을 저장합니다 (Ctrl+S 또는 Cmd+S).

커밋, 푸시 및 병렬 작업 관찰

GitHub 에 변경 사항을 커밋하여 매트릭스 (matrix) 기능을 실제로 확인해 보겠습니다.

저장소 디렉토리에 있는지 확인합니다:

cd ~/project/github-actions-demo

변경 사항을 스테이징합니다:

git add .

변경 사항을 커밋합니다:

git commit -m "Add matrix strategy for Node.js versions"

GitHub 의 원격 저장소로 변경 사항을 푸시합니다:

git push

인증 관련 참고 사항: git push를 실행하면 WebIDE 가 자동으로 인증을 요청하는 팝업을 띄웁니다. 다음의 상세 단계를 따르십시오:

"The extension 'GitHub' wants to sign in using GitHub." 라는 메시지와 함께 팝업이 나타납니다. Allow를 클릭합니다.
새로운 알림이 나타납니다. **"Copy&Continue to GitHub"**를 클릭한 다음, 다음 프롬프트에서 **"Open"**을 클릭합니다.
열리는 브라우저 창에서 GitHub 계정으로 로그인하고 복사된 인증 코드를 입력합니다. 인증을 확인하면 페이지가 자동으로 닫힙니다.
몇 초 기다리면 터미널에서 푸시 작업이 성공적으로 완료되는 것을 볼 수 있습니다.

개인 정보 보호 참고 사항: WebIDE 는 인증 목적으로 귀하의 GitHub 계정에 대한 전체 액세스를 요청합니다. 개인 정보 보호에 대해 걱정할 필요가 없습니다. 현재 랩 (lab) 을 완료하면 LabEx VM 은 즉시 파기되며, 귀하의 자격 증명 및 인증 정보는 유지되지 않습니다.

이 인증 과정은 사용자 이름이나 Personal Access Token(개인 액세스 토큰) 의 수동 구성이 필요하지 않습니다.

GitHub 에서 확인하기

웹 브라우저에서 GitHub 에 있는 저장소로 이동합니다.
Actions 탭을 클릭합니다.
최신 워크플로 실행 (workflow run) 을 클릭합니다.
왼쪽 사이드바 (또는 메인 그래프 보기) 에서 이제 build 그룹 아래에 세 개의 별도 작업이 나열된 것을 볼 수 있습니다:
- build (18)
- build (20)
- build (22)
이 작업들은 병렬로 (또는 거의 병렬로) 실행됩니다. 각 작업을 클릭하여 Use Node.js 단계가 요청된 특정 버전을 설정했는지 확인할 수 있습니다.

GitHub Actions matrix builds

요약

본 실습에서는 GitHub Actions 에서 Matrix Strategy를 사용하는 방법을 배웠습니다. 다음을 수행했습니다:

strategy: matrix를 사용하여 여러 Node.js 버전을 포함하는 매트릭스를 정의했습니다.
워크플로우 단계를 업데이트하여 매트릭스 컨텍스트 ($ {{ matrix.node-version }}) 에서 버전을 동적으로 사용하도록 했습니다.
각 매트릭스 작업에 대해 아티팩트 이름이 고유하도록 보장했습니다.

이 강력한 기능을 사용하면 코드 중복을 거의 없이 광범위한 구성에 대해 프로젝트를 검증할 수 있습니다.