# Node.js 빌드 및 테스트

CI(연속 통합) 워크플로를 만들어 Node.js 프로젝트를 빌드하고 테스트하는 방법을 알아보세요.

> \[!NOTE]
> GitHub Enterprise Server 호스트 실행기는 현재 GitHub에서 지원되지 않습니다.

## 소개

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

## 필수 조건

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

* [워크플로 작성](/ko/enterprise-server@3.22/actions/how-tos/write-workflows)
* [Node.js 시작](https://nodejs.org/learn/getting-started/introduction-to-nodejs)

### GitHub Enterprise Server에서 자체 호스팅 러너 사용하기

`actions/setup-LANGUAGE`에서 설정 작업(GitHub Enterprise Server와 같은)을 수행할 때, 인터넷에 연결할 수 없는 셀프 호스팅 러너에 도구 캐시를 설정해야 할 수도 있습니다. 자세한 내용은 [인터넷에 액세스할 수 없는 자체 호스팅 실행기에서 도구 캐시 설정](/ko/enterprise-server@3.22/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access)을(를) 참조하세요.

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

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

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

1. GitHub에서 리포지토리의 기본 페이지로 이동합니다.

2. 리포지토리 이름에서 **<svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-play" aria-label="play" role="img"><path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"></path></svg> 작업**을 클릭합니다.

   !["github/docs" 리포지토리의 탭 스크린샷. "작업" 탭은 주황색 윤곽선으로 강조 표시됩니다.](/assets/images/help/repository/actions-tab-global-nav-update.png)

3. 리포지토리에 워크플로가 이미 있는 경우 **새 워크플로**를 클릭합니다.

4. "워크플로 선택" 페이지에는 권장되는 워크플로 템플릿의 선택 항목이 표시됩니다. "Node.js"를 검색합니다.

5. **지속적 통합**을 클릭하여 워크플로 선택을 필터링합니다.

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

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

   ```yaml copy
   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@v6
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v7
         with:
           node-version: ${{ matrix.node-version }}
           cache: 'npm'
       - run: npm ci
       - run: npm run build --if-present
       - run: npm test
   ```

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

8. **변경 내용 커밋**을 클릭합니다.

## Node.js 버전 지정

Node.js 버전을 지정하는 가장 쉬운 방법은 `setup-node`에서 제공하는 GitHub 작업을 사용하는 것입니다. 자세한 내용은 [`setup-node`](https://github.com/actions/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의 각 버전은 동일한 단계를 실행하는 작업을 만듭니다.

각 작업은 `node-version` 컨텍스트를 사용하여 매트릭스 `matrix` 배열에 정의된 값에 액세스할 수 있습니다.
`setup-node` 작업은 컨텍스트를 `node-version` 입력으로 사용합니다.
`setup-node` 작업은 코드를 빌드하고 테스트하기 전에 다른 Node.js 버전으로 각 작업을 구성합니다. 행렬 전략 및 컨텍스트에 대한 자세한 내용은 [GitHub Actions에 대한 워크플로 구문](/ko/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategymatrix) 및 [문맥 참조](/ko/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts)을(를) 참조하세요.

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

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

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

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

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

```yaml copy
name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

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

Node.js 버전을 GitHub 지정하지 않으면 환경의 기본 Node.js 버전을 사용합니다.
자세한 내용은 [GitHub 호스팅 실행기](/ko/enterprise-server@3.22/actions/concepts/runners/github-hosted-runners#preinstalled-software-for-github-owned-images)을(를) 참조하세요.

## 종속성 설치

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

종속성을 캐시하여 워크플로 속도를 높일 수도 있습니다. 자세한 내용은 [종속성 캐싱 참조](/ko/enterprise-server@3.22/actions/reference/workflows-and-actions/dependency-caching)을(를) 참조하세요.

### npm을 사용한 예시

이 예시에서는 `package-lock.json` 또는 `npm-shrinkwrap.json` 파일에 버전을 설치하고 잠금 파일이 업데이트를 방지합니다. 일반적으로 `npm ci`를 사용하는 것이 `npm install`을 실행하는 것보다 빠릅니다. 자세한 내용은 [`npm ci`](https://docs.npmjs.com/cli/ci.html) 및 [더 빠르고 안정적인 빌드를 위한 `npm ci` 소개](https://blog.npmjs.org/post/171556855892/introducing-npm-ci-for-faster-more-reliable)를 참조하세요.

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

`npm install`을 사용하면 `package.json` 파일에 정의된 종속성이 설치됩니다. 자세한 내용은 [`npm install`](https://docs.npmjs.com/cli/install)를 참조하세요.

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

### Yarn을 사용한 예시

이 예시에서는 `yarn.lock` 파일에 정의된 종속성을 설치하고 `yarn.lock` 파일 업데이트를 방지합니다. 자세한 내용은 [`yarn install`](https://yarnpkg.com/en/docs/cli/install)를 참조하세요.

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

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

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

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

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

프라이빗 레지스트리에 인증하려면 npm 인증 토큰을 비밀로 저장해야 합니다. 예를 들어 `NPM_TOKEN`이라는 레지스트리 비밀을 만듭니다. 자세한 내용은 [GitHub Actions에서 비밀 사용](/ko/enterprise-server@3.22/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)을(를) 참조하세요.

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

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

```yaml copy
steps:
- uses: actions/checkout@v6
- name: Use Node.js
  uses: actions/setup-node@v7
  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` 파일을 만듭니다.

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

### 종속성 캐싱 예시

[
`setup-node`작업](https://github.com/actions/setup-node)을 사용하여 종속성을 캐시하고 복원할 수 있습니다.

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

```yaml copy
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v7
  with:
    node-version: '20'
    cache: 'npm'
- run: npm install
- run: npm test
```

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

```yaml copy
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v7
  with:
    node-version: '20'
    cache: 'yarn'
- run: yarn
- run: yarn test
```

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

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

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

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

사용자 지정 요구사항이 있거나 캐싱에 대한 세부적인 제어가 필요한 경우 [`cache` 작업](https://github.com/marketplace/actions/cache)을 사용할 수 있습니다. 자세한 내용은 [종속성 캐싱 참조](/ko/enterprise-server@3.22/actions/reference/workflows-and-actions/dependency-caching)을(를) 참조하세요.

## 코드 빌드 및 테스트

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

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

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

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

## 패키지 레지스트리에 게시

CI 테스트에 통과하면 Node.js 패키지를 패키지 레지스트리에 게시하도록 워크플로를 구성할 수 있습니다. npm에 게시하는 GitHub Packages방법에 대한 자세한 내용은 [Node.js 패키지 게시](/ko/enterprise-server@3.22/actions/tutorials/publish-packages/publish-nodejs-packages)을 참조하세요.