はじめに
このガイドでは、Node.jsのコードのビルドとテストを行う継続的インテグレーション(CI)ワークフローの作成方法を紹介します。 CIテストにパスしたなら、コードをデプロイしたりパッケージを公開したりすることになるでしょう。
必要な環境
Node.js、YAML、ワークフローの設定オプションと、ワークフローファイルの作成方法についての基本的な知識を持っておくことをおすすめします。 詳しい情報については、以下を参照してください。
Node.jsワークフローテンプレートでの開始
GitHubは、ほとんどのNode.jsプロジェクトで使えるNode.jsのワークフローテンプレートを提供しています。 このガイドには、カスタマイズして利用できるnpm及びYarnの例が含まれます。 詳しい情報についてはNode.jsのワークフローテンプレートを参照してください。
手早く始めるために、テンプレートをリポジトリの.github/workflows
ディレクトリに追加してください。
name: Node.js CI
on:
push:
branches: [ $default-branch ]
pull_request:
branches: [ $default-branch ]
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: windows-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のコンテキストと式構文」を参照してください。
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バージョンを指定してビルドとテストを行うこともできます。
strategy:
matrix:
node-version: [8.16.2, 10.17.0]
または、Node.jsの1つのバージョンを使ってビルドとテストを行うこともできます。
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のバージョンを使います。 詳しい情報については、「GitHub ホストランナーの仕様」を参照してください。
依存関係のインストール
GitHubホストランナーには、依存関係マネージャーのnpmとYarnがインストールされています。 コードのビルドとテストに先立って、npmやYarnを使ってワークフロー中で依存関係をインストールできます。 Windows及びLinuxのGitHubホストランナーには、Grunt、Gulp、Bowerもインストールされています。
GitHubホストランナーを使用する場合、依存関係をキャッシュしてワークフローの実行を高速化することもできます。 詳しい情報については、「ワークフローを高速化するための依存関係のキャッシュ」を参照してください。
npmの利用例
以下の例では、package.jsonファイルで定義された依存関係がインストールされます。 詳しい情報についてはnpm install
を参照してください。
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」を参照してください。
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
を参照してください。
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ファイルの更新を回避できます。
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
を参照してください。
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
アクションを参照してください。
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
を実行しているなら、それらのコマンドをワークフローファイルに追加します。
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パッケージの公開」を参照してください。