ドキュメントには頻繁に更新が加えられ、その都度公開されています。本ページの翻訳はまだ未完成な部分があることをご了承ください。最新の情報については、英語のドキュメンテーションをご参照ください。本ページの翻訳に問題がある場合はこちらまでご連絡ください。
GitHub AEは、現在限定リリース中です。詳細については営業チームにお問い合わせください。

Node.js のビルドとテスト

Node.jsプロジェクトのビルドとテストのための継続的インテグレーション(CI)ワークフローを作成できます。

GitHub ActionsはGitHub Free、GitHub Pro、GitHub FreeのOrganization、GitHub Team、GitHub Enterprise Cloud、GitHub AEで利用できます。 GitHub Actionsは、レガシーのリポジトリごとのプランを使っているアカウントが所有しているプライベートリポジトリでは利用できません。

ノート: GitHub Actionsは現在GitHub AEでベータです。

はじめに

このガイドでは、Node.jsのコードのビルドとテストを行う継続的インテグレーション(CI)ワークフローの作成方法を紹介します。 CIテストにパスしたなら、コードをデプロイしたりパッケージを公開したりすることになるでしょう。

必要な環境

Node.js、YAML、ワークフローの設定オプションと、ワークフローファイルの作成方法についての基本的な知識を持っておくことをおすすめします。 詳しい情報については、以下を参照してください。

Node.jsワークフローテンプレートでの開始

GitHubは、ほとんどのNode.jsプロジェクトで使えるNode.jsのワークフローテンプレートを提供しています。 このガイドには、カスタマイズして利用できるnpm及びYarnの例が含まれます。 詳しい情報についてはNode.jsのワークフローテンプレートを参照してください。

手早く始めるために、テンプレートをリポジトリの.github/workflowsディレクトリに追加してください。 以下に示すワークフローは、リポジトリのデフォルトブランチが main であることを前提としています。

YAML
name: Node.js CI

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

jobs:
  build:

    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [10.x, 12.x, 14.x, 15.x]

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

様々なオペレーティングシステム上での実行

スターターワークフローテンプレートは、GitHubホストubuntu-latestランナーを使ってLinux上で実行されるようにジョブを設定します。 runs-onキーを変更し、異なるペレーティングシステムでジョブを実行するようにすることができます。 たとえば、GitHubホストのWindowsランナーを使うことができます。

runs-on: windows-latest

あるいはGitHubホストのmacOSランナーで実行させることもできます。

runs-on: macos-latest

Dockerコンテナ上でジョブを実行させたり、独自のインフラストラクチャ上で動作するセルフホストランナーを提供したりすることもできます。 詳細については、「GitHub Actionsのワークフロー構文」を参照してください。

Node.jsのバージョンの指定

最も簡単にNode.jsのバージョンを指定する方法は、GitHubが提供するsetup-nodeアクションを使うことです。 詳しい情報についてはsetup-nodeを参照してください。

setup-nodeアクションはNode.jsのバージョンを入力として取り、ランナー上でそのバージョンを設定します。 setup-nodeは各ランナー上のツールキャッシュから指定されたNode.jsのバージョンを見つけ、必要なバイナリをPATHに追加します。設定されたバイナリは、ジョブでそれ以降永続化されます。 setup-nodeアクションの利用は、GitHub ActionsでNode.jsを使うための推奨される方法です。これは、そうすることで様々なランナーや様々なバージョンのNode.jsで一貫した振る舞いが保証されるためです。 セルフホストランナーを使っている場合は、Node.jsをインストールしてPATHに追加しなければなりません。

このテンプレートには、Node.jsの4つのバージョン、10.x、12.x、14.x、15.xでコードをビルドしてテストするマトリクス戦略が含まれています。 この'x'はワイルドカードキャラクターで、そのバージョンで利用できる最新のマイナー及びパッチリリースにマッチします。 node-version配列で指定されたNode.jsの各バージョンに対して、同じステップを実行するジョブが作成されます。

それぞれのジョブは、配列node-version のマトリクスで定義された値に、matrixコンテキストを使ってアクセスできます。 setup-nodeアクションは、このコンテキストをnode-versionのインプットとして使います。 setup-nodeアクションは、コードのビルドとテストに先立って、様々なNode.jsのバージョンで各ジョブを設定します。 マトリクス戦略とコンテキストに関する詳しい情報については、「GitHub Actionsのワークフロー構文」及び「GitHub Actionsのコンテキストと式構文」を参照してください。

YAML
strategy:
  matrix:
    node-version: [10.x, 12.x, 14.x, 15.x]

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

あるいは、厳密にNode.jsバージョンを指定してビルドとテストを行うこともできます。

YAML
strategy:
  matrix:
    node-version: [8.16.2, 10.17.0]

または、Node.jsの1つのバージョンを使ってビルドとテストを行うこともできます。

YAML
name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

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

Node.js のバージョンを指定しない場合、

GitHub は環境のデフォルトの Node.js バージョンを使用します。 AEホストランナー に必要なソフトウェアがインストールされていることを確認する方法については、「カスタムイメージの作成」を参照してください。

依存関係のインストール

GitHubホストランナーには、依存関係マネージャーのnpmとYarnがインストールされています。 コードのビルドとテストに先立って、npmやYarnを使ってワークフロー中で依存関係をインストールできます。 Windows及びLinuxのGitHubホストランナーには、Grunt、Gulp、Bowerもインストールされています。

GitHubホストランナーを使用する場合、依存関係をキャッシュしてワークフローの実行を高速化することもできます。 詳しい情報については、「ワークフローを高速化するための依存関係のキャッシュ」を参照してください。

npmの利用例

以下の例では、package.jsonファイルで定義された依存関係がインストールされます。 詳しい情報についてはnpm installを参照してください。

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

npm ciを使うと、 package-lock.jsonあるいはnpm-shrinkwrap.jsonファイル中のバージョンがインストールされ、ロックファイルの更新を回避できます。 概してnpm ciは、npm installを実行するよりも高速です。 詳しい情報についてはnpm ci及び「Introducing npm ci for faster, more reliable builds」を参照してください。

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

Yarnの利用例

以下の例では、package.jsonファイルで定義された依存関係がインストールされます。 詳しい情報についてはyarn installを参照してください。

YAML
steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v1
  with:
    node-version: '12.x'
- name: Install dependencies
  run: yarn

あるいは--frozen-lockfileを渡してyarn.lockファイル中のバージョンをインストールし、yarn.lockファイルの更新を回避できます。

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

プライベートレジストリの利用と.npmrcファイルの作成の例

setup-nodeアクションを使って、デフォルトのレジストリとスコープを設定するローカルの.npmrcファイルをランナー上に作成できます。 setup-nodeアクションは、プライベートリポジトリへのアクセスやnodeパッケージの公開に使われる認証トークンも入力として受け付けます。 詳しい情報についてはsetup-nodeを参照してください。

プライベートレジストリに対して認証するには、npm 認証トークンをシークレットとして保存する必要があります。 たとえば、NPM_TOKEN というリポジトリシークレットを作成します。 詳しい情報については、「暗号化されたシークレットの作成と利用」を参照してください。

以下の例では、NPM_TOKENというシークレットにはnpmの認証トークンが保存されます。 setup-nodeアクションは、環境変数のNODE_AUTH_TOKENからnpmの認証トークンを読み取るよう.npmrcファイルを設定します。 setup-node アクションを使用して .npmrc ファイルを作成する場合は、npm 認証トークンを含むシークレットを使用して NODE_AUTH_TOKEN 環境変数を設定する必要があります。

依存関係をインストールする前に、setup-nodeアクションを使って.npmrcファイルを作成してください。 このアクションには2つの入力パラメーターがあります。 node-versionパラメーターはNode.jsのバージョンを設定し、registry-urlパラメーターはデフォルトのレジストリを設定します。 パッケージレジストリがスコープを使うなら、scopeパラメーターを使わなければなりません。 詳しい情報についてはnpm-scopeを参照してください。

YAML
steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v1
  with:
    always-auth: true
    node-version: '12.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

依存関係のキャッシングの例

GitHub ホストランナーを使用する場合、一意のキーを使用して依存関係をキャッシュし、cache アクションを使用して将来のワークフローを実行するときに依存関係を復元できます。 詳しい情報については「ワークフローを高速化するための依存関係のキャッシング」及びcacheアクションを参照してください。

YAML
steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v1
  with:
    node-version: '12.x'
- name: Cache Node.js modules
  uses: actions/cache@v2
  with:
    # npm cache files are stored in `~/.npm` on Linux/macOS
    path: ~/.npm
    key: ${{ runner.OS }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.OS }}-node-
      ${{ runner.OS }}-
- name: Install dependencies
  run: npm ci

コードのビルドとテスト

ローカルで使うのと同じコマンドを、コードのビルドとテストに使えます。 たとえばpackage.jsonファイルで定義されたビルドのステップを実行するのにnpm run buildを実行し、テストスイートを実行するのにnpm testを実行しているなら、それらのコマンドをワークフローファイルに追加します。

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

成果物としてのワークフローのデータのパッケージ化

ビルドとテストのステップの成果物を保存し、ジョブの完了後に見ることができます。 たとえば、ログファイル、コアダンプ、テスト結果、スクリーンショットを保存する必要があるかもしれません。 詳しい情報については「成果物を利用してワークフローのデータを永続化する」を参照してください。

パッケージレジストリへの公開

CIテストにパスした後、Node.jsパッケージをパッケージレジストリに公開するようにワークフローを設定できます。 npm及びGitHub Packagesへの公開に関する詳しい情報については「Node.jsパッケージの公開」を参照してください。

このドキュメントは役立ちましたか?プライバシーポリシー

これらのドキュメントを素晴らしいものにするのを手伝ってください!

GitHubのすべてのドキュメントはオープンソースです。間違っていたり、はっきりしないところがありましたか?Pull Requestをお送りください。

コントリビューションを行う

OR, コントリビューションの方法を学んでください。

問題がまだ解決していませんか?

GitHubコミュニティで質問するサポートへの連絡