注: GitHub ホステッド ランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。
はじめに
このガイドでは、Node.jsのコードのビルドとテストを行う継続的インテグレーション(CI)ワークフローの作成方法を紹介します。 CIテストにパスしたなら、コードをデプロイしたりパッケージを公開したりすることになるでしょう。
前提条件
Node.js、YAML、ワークフローの設定オプションと、ワークフローファイルの作成方法についての基本的な知識を持っておくことをおすすめします。 詳細については、次を参照してください。
GitHub Enterprise Server上でのセルフホストランナーの利用
GitHub Enterprise Server でセルフホスト ランナーと合わせてセットアップ アクション (actions/setup-LANGUAGE
など) を使用するときに、インターネットにアクセスできないランナー上にツール キャッシュを設定する必要がある場合があります。 詳しくは、「インターネットにアクセスできないセルフホストランナーにツールキャッシュを設定する」を参照してください。
Node.js スターター ワークフローの使用
GitHub では、ほとんどの Node.js プロジェクトで使用できる Node.js のスターター ワークフローを提供しています。 このガイドには、スターター ワークフローをカスタマイズして利用できる npm および Yarn の例が含まれます。 詳細については、Node.js のスターター ワークフローに関するページを参照してください。
既定のスターター ワークフローは、ビルドとテストのワークフローを構築するときに適した出発点であり、プロジェクトの要求に合わせてこのスターター ワークフローをカスタマイズできます。
すぐに作業を開始するには、リポジトリの .github/workflows
ディレクトリにスターター ワークフローを追加します。
# ワークフローの名前です。 GitHub では、ワークフローの名前がリポジトリの [アクション] タブに表示されます。`name` を省略すると、GitHub は、リポジトリのルートに対して相対的なワークフロー ファイル パスを表示します。 name: Node.js CI # This example workflow assumes that the default branch for your repository is `main`. If the default branch has a different name, edit this example and add your repository's default branch. on: push: branches: [ main ] pull_request: branches: [ main ] # jobs: build: # <!-- This is a YAML comment for use in annotated code examples. --> # このワークフローは、別のオペレーティング システムを使用して実行できます。 # # スターター ワークフローは、GitHub ホスト `ubuntu-latest` ランナーを使って Linux 上で実行するジョブを設定します。 `runs-on` キーを変更すると、別のオペレーティング システムでジョブを実行するようにできます。 # # たとえば、`runs-on: windows-latest` を指定すると、GitHub がホストする Windows ランナーを使うことができます。 あるいは、`runs-on: macos-latest` を使用すると、GitHub がホストする macOS ランナーで実行させることもできます。 # # Dockerコンテナ上でジョブを実行させたり、独自のインフラストラクチャ上で動作するセルフホストランナーを提供したりすることもできます。 詳しくは、「[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)」を参照してください。 runs-on: ubuntu-latest # This job uses a matrix strategy to run the job four times, once for each specified Node version. For more information, see "[AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs)." strategy: matrix: node-version: [14.x, 16.x, 18.x, 20.x] # steps: # このステップでは、`actions/checkout` アクションで、ランナーにリポジトリのコピーをダウンロードします。 - uses: actions/checkout@v4 # This step uses the `actions/setup-node` action to set up Node.js for each version indicated by the `matrix.node-version` key above. - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-node@v4 with: node-version: ${{ matrix.node-version }} # This step runs `npm ci` to install any dependencies listed in your `package.json` file. - run: npm ci # This step runs the `build` script if there is one specified under the `scripts` key in your `package.json` file. - run: npm run build --if-present # This step runs the `test` script that is specified under the `scripts` key in your `package.json` file. - run: npm test
name: Node.js CI
ワークフローの名前です。 GitHub では、ワークフローの名前がリポジトリの [アクション] タブに表示されます。name
を省略すると、GitHub は、リポジトリのルートに対して相対的なワークフロー ファイル パスを表示します。
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
This example workflow assumes that the default branch for your repository is main
. If the default branch has a different name, edit this example and add your repository's default branch.
jobs:
build:
runs-on: ubuntu-latest
このワークフローは、別のオペレーティング システムを使用して実行できます。
スターター ワークフローは、GitHub ホスト ubuntu-latest
ランナーを使って Linux 上で実行するジョブを設定します。 runs-on
キーを変更すると、別のオペレーティング システムでジョブを実行するようにできます。
たとえば、runs-on: windows-latest
を指定すると、GitHub がホストする Windows ランナーを使うことができます。 あるいは、runs-on: macos-latest
を使用すると、GitHub がホストする macOS ランナーで実行させることもできます。
Dockerコンテナ上でジョブを実行させたり、独自のインフラストラクチャ上で動作するセルフホストランナーを提供したりすることもできます。 詳しくは、「GitHub Actions のワークフロー構文」を参照してください。
strategy:
matrix:
node-version: [14.x, 16.x, 18.x, 20.x]
This job uses a matrix strategy to run the job four times, once for each specified Node version. For more information, see "ジョブにマトリックスを使用する."
steps:
- uses: actions/checkout@v4
このステップでは、actions/checkout
アクションで、ランナーにリポジトリのコピーをダウンロードします。
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
This step uses the actions/setup-node
action to set up Node.js for each version indicated by the matrix.node-version
key above.
- run: npm ci
This step runs npm ci
to install any dependencies listed in your package.json
file.
- run: npm run build --if-present
This step runs the build
script if there is one specified under the scripts
key in your package.json
file.
- run: npm test
This step runs the test
script that is specified under the scripts
key in your package.json
file.
# ワークフローの名前です。 GitHub では、ワークフローの名前がリポジトリの [アクション] タブに表示されます。`name` を省略すると、GitHub は、リポジトリのルートに対して相対的なワークフロー ファイル パスを表示します。
name: Node.js CI
# This example workflow assumes that the default branch for your repository is `main`. If the default branch has a different name, edit this example and add your repository's default branch.
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
#
jobs:
build:
# <!-- This is a YAML comment for use in annotated code examples. -->
# このワークフローは、別のオペレーティング システムを使用して実行できます。
#
# スターター ワークフローは、GitHub ホスト `ubuntu-latest` ランナーを使って Linux 上で実行するジョブを設定します。 `runs-on` キーを変更すると、別のオペレーティング システムでジョブを実行するようにできます。
#
# たとえば、`runs-on: windows-latest` を指定すると、GitHub がホストする Windows ランナーを使うことができます。 あるいは、`runs-on: macos-latest` を使用すると、GitHub がホストする macOS ランナーで実行させることもできます。
#
# Dockerコンテナ上でジョブを実行させたり、独自のインフラストラクチャ上で動作するセルフホストランナーを提供したりすることもできます。 詳しくは、「[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)」を参照してください。
runs-on: ubuntu-latest
# This job uses a matrix strategy to run the job four times, once for each specified Node version. For more information, see "[AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs)."
strategy:
matrix:
node-version: [14.x, 16.x, 18.x, 20.x]
#
steps:
# このステップでは、`actions/checkout` アクションで、ランナーにリポジトリのコピーをダウンロードします。
- uses: actions/checkout@v4
# This step uses the `actions/setup-node` action to set up Node.js for each version indicated by the `matrix.node-version` key above.
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
# This step runs `npm ci` to install any dependencies listed in your `package.json` file.
- run: npm ci
# This step runs the `build` script if there is one specified under the `scripts` key in your `package.json` file.
- run: npm run build --if-present
# This step runs the `test` script that is specified under the `scripts` key in your `package.json` file.
- run: npm test
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
に追加する必要があります。
スターター ワークフローには、4 つの Node.js バージョン (14.x、16.x、18.x、および 20.x) を使用してコードをビルドおよびテストするマトリックス戦略が含まれています。 この'x'はワイルドカードキャラクターで、そのバージョンで利用できる最新のマイナー及びパッチリリースにマッチします。 node-version
配列で指定された Node.js の各バージョンに対して、同じステップを実行するジョブが作成されます。
各ジョブでは、matrix
コンテキストを使用してマトリックス node-version
配列で定義された値にアクセスできます。 setup-node
アクションでは、コンテキストが node-version
入力として使用されます。 setup-node
アクションでは、コードのビルドとテストに先立って、様々な Node.js のバージョンで各ジョブを設定します。 マトリックスの戦略とコンテキストについて詳しくは、「GitHub Actions のワークフロー構文」と「コンテキスト」をご覧ください。
strategy: matrix: node-version: [14.x, 16.x, 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: [14.x, 16.x, 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バージョンを指定してビルドとテストを行うこともできます。
strategy: matrix: node-version: [10.17.0, 17.9.0]
strategy:
matrix:
node-version: [10.17.0, 17.9.0]
または、Node.jsの1つのバージョンを使ってビルドとテストを行うこともできます。
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: '18.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: '18.x'
- run: npm ci
- run: npm run build --if-present
- run: npm test
Node.jsのバージョンを指定しなかった場合、GitHubは環境のデフォルトのNode.jsのバージョンを使います。 詳しくは、「Using GitHub-hosted runners」をご覧ください。
依存関係のインストール
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
の導入」を参照してください。
steps: - uses: actions/checkout@v4 - name: Use Node.js uses: actions/setup-node@v4 with: node-version: '18.x' - name: Install dependencies run: npm ci
steps:
- uses: actions/checkout@v4
- name: Use Node.js
uses: actions/setup-node@v4
with:
node-version: '18.x'
- name: Install dependencies
run: npm ci
npm install
を使うと、package.json ファイルで定義された依存関係がインストールされます。 詳細については、「npm install
」を参照してください。
steps: - uses: actions/checkout@v4 - name: Use Node.js uses: actions/setup-node@v4 with: node-version: '18.x' - name: Install dependencies run: npm install
steps:
- uses: actions/checkout@v4
- name: Use Node.js
uses: actions/setup-node@v4
with:
node-version: '18.x'
- name: Install dependencies
run: npm install
Yarnの利用例
この例では、yarn.lock ファイルで定義されている依存関係がインストールされ、yarn.lock ファイルの更新が防止されます。 詳細については、「yarn install
」を参照してください。
steps: - uses: actions/checkout@v4 - name: Use Node.js uses: actions/setup-node@v4 with: node-version: '18.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: '18.x'
- name: Install dependencies
run: yarn --frozen-lockfile
または、package.json ファイルで定義されている依存関係をインストールすることもできます。
steps: - uses: actions/checkout@v4 - name: Use Node.js uses: actions/setup-node@v4 with: node-version: '18.x' - name: Install dependencies run: yarn
steps:
- uses: actions/checkout@v4
- name: Use Node.js
uses: actions/setup-node@v4
with:
node-version: '18.x'
- name: Install dependencies
run: yarn
プライベートレジストリの利用と.npmrcファイルの作成の例
setup-node
アクションを使用して、既定のレジストリとスコープを構成するローカルの .npmrc ファイルをランナーに作成できます。 setup-node
アクションは、プライベート リポジトリへのアクセスや 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 ファイルを作成します。 このアクションには2つの入力パラメーターがあります。 node-version
パラメーターによって、Node.js のバージョンが設定され、registry-url
パラメーターによって既定のレジストリーが設定されます。 パッケージ レジストリでスコープが使用されている場合は、scope
パラメーターを使用する必要があります。 詳細については、「npm-scope
」を参照してください。
steps: - uses: actions/checkout@v4 - name: Use Node.js uses: actions/setup-node@v4 with: always-auth: true node-version: '18.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: '18.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 の依存関係をキャッシュします。
steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '14' cache: 'npm' - run: npm install - run: npm test
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '14'
cache: 'npm'
- run: npm install
- run: npm test
次の例では Yarn の依存関係をキャッシュします。
steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '14' cache: 'yarn' - run: yarn - run: yarn test
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '14'
cache: 'yarn'
- run: yarn
- run: yarn test
次の例では pnpm (v6.10+) の依存関係をキャッシュします。
# このワークフローは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: '14' 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: '14'
cache: 'pnpm'
- run: pnpm install
- run: pnpm test
カスタム要件がある場合、またはキャッシュに対してより細かい制御が必要な場合は、cache
アクションを使用できます。 詳しくは、「依存関係をキャッシュしてワークフローのスピードを上げる」を参照してください。
コードのビルドとテスト
ローカルで使うのと同じコマンドを、コードのビルドとテストに使えます。 たとえば、npm run build
を実行することで、package.json ファイルで定義されたビルド ステップを実行し、さらに npm test
を実行することでテスト スイートを実行する場合は、それらのコマンドをワークフロー ファイルに追加します。
steps: - uses: actions/checkout@v4 - name: Use Node.js uses: actions/setup-node@v4 with: node-version: '18.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: '18.x'
- run: npm install
- run: npm run build --if-present
- run: npm test
成果物としてのワークフローのデータのパッケージ化
ビルドとテストのステップの成果物を保存し、ジョブの完了後に見ることができます。 たとえば、ログファイル、コアダンプ、テスト結果、スクリーンショットを保存する必要があるかもしれません。 詳しくは、「ワークフロー データを成果物として保存する」を参照してください。
パッケージレジストリへの公開
CIテストにパスした後、Node.jsパッケージをパッケージレジストリに公開するようにワークフローを設定できます。 npm と GitHub Packages への公開について詳しくは、「Node.jsパッケージの公開」をご覧ください。