Node.js 빌드 및 테스트

참고: GitHub 호스트 실행기는 현재 GitHub Enterprise Server에서 지원되지 않습니다. GitHub public roadmap에 예정된 향후 지원에 대해 자세히 알아볼 수 있습니다.

소개

이 가이드에서는 Node.js 코드를 빌드하고 테스트하는 CI(연속 통합) 워크플로를 만드는 방법을 보여 줍니다. CI 테스트에 통과하면 코드를 배포하거나 패키지를 게시할 수 있습니다.

필수 조건

Node.js, YAML, 워크플로 구성 옵션과 워크플로 파일을 만드는 방법을 기본적으로 이해하는 것이 좋습니다. 자세한 내용은 다음을 참조하세요.

"워크플로 작성"
“Node.js 시작”

GitHub Enterprise Server에서 자체 호스팅 실행기 사용

실행기를 자체 호스팅하는 GitHub Enterprise Server에서 actions/setup-LANGUAGE 같은 설정 작업을 사용할 경우 인터넷에 액세스할 수 없는 실행기에서 도구 캐시를 설정해야 할 수 있습니다. 자세한 정보는 "인터넷에 액세스할 수 없는 자체 호스팅 실행기에서 도구 캐시 설정"을(를) 참조하세요.

Node.js 워크플로 템플릿 사용

빠르게 시작하려면 워크플로 템플릿을 리포지토리의 .github/workflows 디렉터리에 추가합니다.

GitHub는 대부분의 Node.js 기반 Java 프로젝트에서 작동하는 Node.js 워크플로 템플릿을 제공합니다. 이 가이드의 후속 섹션에서는 이 워크플로 템플릿을 사용자 지정하는 방법에 대한 예시를 제공합니다.

GitHub에서 리포지토리의 기본 페이지로 이동합니다.
리포지토리 이름 아래에서 작업을 클릭합니다.
리포지토리에 워크플로가 이미 있는 경우 새 워크플로를 클릭합니다.
"워크플로 선택" 페이지에는 권장되는 워크플로 템플릿의 선택 항목이 표시됩니다. "Node.js"를 검색합니다.
지속적 통합을 클릭하여 워크플로 선택을 필터링합니다.

"Node.js" 워크플로에서 구성을 클릭합니다.

“Node.js” 워크플로 템플릿을 찾을 수 없는 경우 다음 워크플로 코드를 리포지토리의 .github/workflows 디렉터리에 있는 이름이 node.js.yml인 새 파일에 복사합니다.

YAML

name: Node.js CI

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [18.x, 20.x]
        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/

    steps:
    - uses: actions/checkout@v4
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - run: npm ci
    - run: npm run build --if-present
    - run: npm test

name: Node.js CI

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [18.x, 20.x]
        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/

    steps:
    - uses: actions/checkout@v4
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - run: npm ci
    - run: npm run build --if-present
    - run: npm test

필요에 따라 워크플로를 편집합니다. 예를 들어 사용하려는 노드 버전을 변경합니다.
변경 내용 커밋을 클릭합니다.

Node.js 버전 지정

Node.js 버전을 지정하는 가장 쉬운 방법은 GitHub에서 제공하는 setup-node 작업을 사용하는 것입니다. 자세한 내용은 setup-node를 참조하세요.

이 setup-node 작업은 Node.js 버전을 입력으로 사용하고 실행기에서 해당 버전을 구성합니다. setup-node 작업은 각 실행기의 도구 캐시에서 Node.js의 특정 버전을 찾아 필수 이진 파일을 PATH에 추가합니다. 이 이진 파일은 나머지 작업 동안 유지됩니다. setup-node 작업을 사용하는 것은 다양한 실행기 및 Node.js 버전 간에 일관된 동작을 보장하므로 GitHub Actions로 Node.js를 사용하는 데 권장되는 방법입니다. 자체 호스트 실행기를 사용하는 경우 Node.js를 설치하고 이를 PATH에 추가해야 합니다.

워크플로 템플릿에는 node-version에 나열된 Node.js 버전으로 코드를 빌드하고 테스트하는 행렬형 전략이 포함되어 있습니다. ‘x’는 버전에 사용할 수 있는 최신 부 버전 및 패치 릴리스와 일치하는 와일드카드 문자입니다. node-version 배열에 지정된 Node.js의 각 버전은 동일한 단계를 실행하는 작업을 만듭니다.

각 작업은 matrix 컨텍스트를 사용하여 매트릭스 node-version 배열에 정의된 값에 액세스할 수 있습니다. setup-node 작업은 컨텍스트를 node-version 입력으로 사용합니다. setup-node 작업은 코드를 빌드하고 테스트하기 전에 다른 Node.js 버전으로 각 작업을 구성합니다. 행렬 전략 및 컨텍스트에 대한 자세한 내용은 "GitHub Actions에 대한 워크플로 구문" 및 "워크플로 실행에 대한 컨텍스트 정보에 액세스"을(를) 참조하세요.

YAML

strategy:
  matrix:
    node-version: ['18.x', '20.x']

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

strategy:
  matrix:
    node-version: ['18.x', '20.x']

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

또는 정확한 Node.js 버전으로 빌드하고 테스트할 수 있습니다.

YAML

strategy:
  matrix:
    node-version: ['10.17.0', '17.9.0']

strategy:
  matrix:
    node-version: ['10.17.0', '17.9.0']

단일 버전의 Node.js를 사용하여 빌드하고 테스트할 수도 있습니다.

YAML

name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20.x'
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20.x'
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

Node.js 버전을 지정하지 않으면 GitHub에서 환경의 기본 Node.js 버전을 사용합니다. 자세한 내용은 "GitHub 호스팅 실행기 사용" 항목을 참조하세요.

종속성 설치

GitHub 호스트 실행기에는 npm 및 Yarn 종속성 관리자가 설치되어 있습니다. 코드를 빌드하고 테스트하기 전에 npm 및 Yarn을 사용하여 워크플로에 종속성을 설치할 수 있습니다. Windows 및 Linux GitHub호스트 실행기에도 Grunt, Gulp, Bower가 설치되어 있습니다.

종속성을 캐시하여 워크플로 속도를 높일 수도 있습니다. 자세한 내용은 "워크플로 속도를 높이기 위한 종속성 캐싱"을(를) 참조하세요.

npm을 사용한 예시

이 예시에서는 package-lock.json 또는 npm-shrinkwrap.json 파일에 버전을 설치하고 잠금 파일이 업데이트를 방지합니다. 일반적으로 npm ci를 사용하는 것이 npm install을 실행하는 것보다 빠릅니다. 자세한 내용은 npm ci 및 “더 빠르고 안정적인 빌드를 위한 npm ci 소개”를 참조하세요.

YAML

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: npm ci

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: npm ci

npm install을(를) 사용하면 package.json 파일에 정의된 종속성이 설치됩니다. 자세한 내용은 npm install를 참조하세요.

YAML

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: npm install

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: npm install

Yarn을 사용한 예시

이 예시에서는 yarn.lock 파일에 정의된 종속성을 설치하고 yarn.lock 파일에 대한 업데이트를 방지합니다. 자세한 내용은 yarn install를 참조하세요.

YAML

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: yarn --frozen-lockfile

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: yarn --frozen-lockfile

또는 package.json 파일에 정의된 종속성을 설치할 수 있습니다.

YAML

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: yarn

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: yarn

프라이빗 레지스트리를 사용하고 .npmrc 파일을 만드는 예시

setup-node 작업을 사용하여 기본 레지스트리 및 범위를 구성하는 실행기에서 로컬 .npmrc 파일을 만들 수 있습니다. 또한 setup-node 작업은 프라이빗 레지스트리에 액세스하거나 노드 패키지를 게시하는 데 사용되는 입력으로 인증 토큰을 허용합니다. 자세한 내용은 setup-node를 참조하세요.

프라이빗 레지스트리에 인증하려면 npm 인증 토큰을 비밀로 저장해야 합니다. 예를 들어 NPM_TOKEN이라는 레지스트리 비밀을 만듭니다. 자세한 내용은 "GitHub Actions에서 비밀 사용"을(를) 참조하세요.

아래 예시에서 비밀 NPM_TOKEN은 npm 인증 토큰을 저장합니다. setup-node 작업은 NODE_AUTH_TOKEN 환경 변수에서 npm 인증 토큰을 읽도록 .npmrc 파일을 구성합니다. setup-node 작업을 사용하여 .npmrc 파일을 만들 때 npm 인증 토큰이 포함된 비밀로 NODE_AUTH_TOKEN 환경 변수를 설정해야 합니다.

종속성을 설치하기 전에 setup-node 작업을 사용하여 .npmrc 파일을 만듭니다. 작업에는 두 개의 입력 매개 변수가 있습니다. node-version 매개 변수는 Node.js 버전을 설정하고 registry-url 매개 변수는 기본 레지스트리를 설정합니다. 패키지 레지스트리에서 범위를 사용하는 경우 scope 매개 변수를 사용해야 합니다. 자세한 내용은 npm-scope를 참조하세요.

YAML

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    always-auth: true
    node-version: '20.x'
    registry-url: https://registry.npmjs.org
    scope: '@octocat'
- name: Install dependencies
  run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    always-auth: true
    node-version: '20.x'
    registry-url: https://registry.npmjs.org
    scope: '@octocat'
- name: Install dependencies
  run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

위의 예시에서는 다음 콘텐츠가 포함된 .npmrc 파일을 만듭니다.

//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
@octocat:registry=https://registry.npmjs.org/
always-auth=true

종속성 캐싱 예시

setup-node작업을 사용하여 종속성을 캐시하고 복원할 수 있습니다.

다음 예시에서는 npm에 대한 종속성을 캐시합니다.

YAML

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'
- run: npm install
- run: npm test

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'
- run: npm install
- run: npm test

다음 예시에서는 Yarn에 대한 종속성을 캐시합니다.

YAML

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'yarn'
- run: yarn
- run: yarn test

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'yarn'
- run: yarn
- run: yarn test

다음 예시에서는 pnpm(v6.10 이상)에 대한 종속성을 캐시합니다.

YAML

# 이 워크플로는 GitHub에서 인증되지 않은 작업을 사용합니다.
# 작업은 타사에서 제공하며
# 별도의 서비스 약관, 개인정보처리방침, 지원 설명서에서 규정됩니다.
# 참조하세요.

# NOTE: pnpm caching support requires pnpm version >= 6.10.0

steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@0609f0983b7a228f052f81ef4c3d6510cae254ad
  with:
    version: 6.10.0
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'pnpm'
- run: pnpm install
- run: pnpm test

# 이 워크플로는 GitHub에서 인증되지 않은 작업을 사용합니다.
# 작업은 타사에서 제공하며
# 별도의 서비스 약관, 개인정보처리방침, 지원 설명서에서 규정됩니다.
# 참조하세요.

# NOTE: pnpm caching support requires pnpm version >= 6.10.0

steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@0609f0983b7a228f052f81ef4c3d6510cae254ad
  with:
    version: 6.10.0
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'pnpm'
- run: pnpm install
- run: pnpm test

사용자 지정 요구사항이 있거나 캐싱에 대한 세부적인 제어가 필요한 경우 cache 작업을 사용할 수 있습니다. 자세한 내용은 "워크플로 속도를 높이기 위한 종속성 캐싱"을(를) 참조하세요.

코드 빌드 및 테스트

코드를 빌드하고 테스트하기 위해 로컬에서 사용하는 것과 동일한 명령을 사용할 수 있습니다. 예를 들어 npm run build를 실행하여 package.json 파일에 정의된 빌드 단계를 실행하고 npm test를 실행하여 테스트 모음을 실행하는 경우 워크플로 파일에 해당 명령을 추가합니다.

YAML

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- run: npm install
- run: npm run build --if-present
- run: npm test

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- run: npm install
- run: npm run build --if-present
- run: npm test

워크플로 데이터를 아티팩트로 패키지

빌드 및 테스트 단계에서 아티팩트를 저장하여 작업이 완료된 후 볼 수 있습니다. 예를 들어 로그 파일, 코어 덤프, 테스트 결과 또는 스크린샷을 저장해야 할 수 있습니다. 자세한 내용은 "워크플로에서 데이터 저장 및 공유"을(를) 참조하세요.

패키지 레지스트리에 게시

CI 테스트에 통과하면 Node.js 패키지를 패키지 레지스트리에 게시하도록 워크플로를 구성할 수 있습니다. npm 및 GitHub Packages에 게시하는 방법에 대한 자세한 내용은 “Node.js 패키지 게시”를 참조하세요.

이 문서의 내용