Building and testing Node.js

You can create a continuous integration (CI) workflow to build and test your Node.js project.

이 문서의 내용

참고 항목

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

Introduction

This guide shows you how to create a continuous integration (CI) workflow that builds and tests Node.js code. If your CI tests pass, you may want to deploy your code or publish a package.

Prerequisites

We recommend that you have a basic understanding of Node.js, YAML, workflow configuration options, and how to create a workflow file. For more information, see:

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

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

Using a Node.js workflow template

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

GitHub provides a workflow template for Node.js that should work for most Node.js projects. The subsequent sections of this guide give examples of how you can customize this workflow template.

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

  2. 리포지토리 이름 아래에서 작업을 클릭합니다.

    "github/docs" 리포지토리의 탭 스크린샷. "작업" 탭은 주황색 윤곽선으로 강조 표시됩니다.

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

  4. The "Choose a workflow" page shows a selection of recommended workflow templates. Search for "Node.js".

  5. Filter the selection of workflows by clicking Continuous integration.

  6. On the "Node.js" workflow, click Configure.

    If you don't find the "Node.js" workflow template, copy the following workflow code to a new file called node.js.yml in the .github/workflows directory of your repository.

    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

  7. Edit the workflow as required. For example, change the Node versions you want to use.

  8. Click Commit changes.

Specifying the Node.js version

The easiest way to specify a Node.js version is by using the setup-node action provided by GitHub. For more information see, setup-node.

The setup-node action takes a Node.js version as an input and configures that version on the runner. The setup-node action finds a specific version of Node.js from the tools cache on each runner and adds the necessary binaries to PATH, which persists for the rest of the job. Using the setup-node action is the recommended way of using Node.js with GitHub Actions because it ensures consistent behavior across different runners and different versions of Node.js. If you are using a self-hosted runner, you must install Node.js and add it to PATH.

The workflow template includes a matrix strategy that builds and tests your code with the Node.js versions listed in node-version. The 'x' in the version number is a wildcard character that matches the latest minor and patch release available for a version. Each version of Node.js specified in the node-version array creates a job that runs the same steps.

Each job can access the value defined in the matrix node-version array using the matrix context. The setup-node action uses the context as the node-version input. The setup-node action configures each job with a different Node.js version before building and testing code. For more information about matrix strategies and contexts, see GitHub Actions에 대한 워크플로 구문 and 워크플로 실행에 대한 컨텍스트 정보에 액세스.

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 }}

Alternatively, you can build and test with exact Node.js versions.

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

Or, you can build and test using a single version of Node.js too.

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

If you don't specify a Node.js version, GitHub uses the environment's default Node.js version. For more information, see Using GitHub-hosted runners.

Installing dependencies

GitHub-hosted runners have npm and Yarn dependency managers installed. You can use npm and Yarn to install dependencies in your workflow before building and testing your code. The Windows and Linux GitHub-hosted runners also have Grunt, Gulp, and Bower installed.

You can also cache dependencies to speed up your workflow. For more information, see Caching dependencies to speed up workflows.

Example using npm

This example installs the versions in the package-lock.json or npm-shrinkwrap.json file and prevents updates to the lock file. Using npm ci is generally faster than running npm install. For more information, see npm ci and Introducing npm ci for faster, more reliable builds.

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

Using npm install installs the dependencies defined in the package.json file. For more information, see 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

Example using Yarn

This example installs the dependencies defined in the yarn.lock file and prevents updates to the yarn.lock file. For more information, see 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

Alternatively, you can install the dependencies defined in the package.json file.

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

Example using a private registry and creating the .npmrc file

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

To authenticate to your private registry, you'll need to store your npm authentication token as a secret. For example, create a repository secret called NPM_TOKEN. For more information, see Using secrets in GitHub Actions.

In the example below, the secret NPM_TOKEN stores the npm authentication token. The setup-node action configures the .npmrc file to read the npm authentication token from the NODE_AUTH_TOKEN environment variable. When using the setup-node action to create an .npmrc file, you must set the NODE_AUTH_TOKEN environment variable with the secret that contains your npm authentication token.

Before installing dependencies, use the setup-node action to create the .npmrc file. The action has two input parameters. The node-version parameter sets the Node.js version, and the registry-url parameter sets the default registry. If your package registry uses scopes, you must use the scope parameter. For more information, see 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 }}

The example above creates an .npmrc file with the following contents:

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

Example caching dependencies

You can cache and restore the dependencies using the setup-node action.

The following example caches dependencies for npm.

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

The following example caches dependencies for Yarn.

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

The following example caches dependencies for 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

If you have a custom requirement or need finer controls for caching, you can use the cache action. For more information, see Caching dependencies to speed up workflows.

Building and testing your code

You can use the same commands that you use locally to build and test your code. For example, if you run npm run build to run build steps defined in your package.json file and npm test to run your test suite, you would add those commands in your workflow file.

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

Packaging workflow data as artifacts

You can save artifacts from your build and test steps to view after a job completes. For example, you may need to save log files, core dumps, test results, or screenshots. For more information, see Storing and sharing data from a workflow.

Publishing to package registries

You can configure your workflow to publish your Node.js package to a package registry after your CI tests pass. For more information about publishing to npm and GitHub Packages, see Publishing Node.js packages.