ノート: GitHub Actionsは、GitHub Enterprise Server 2.22で限定ベータとして利用可能でした。 ベータは終了しました。 GitHub Actionsは、GitHub Enterprise Server 3.0以降で一般に利用可能になりました。 詳しい情報については、GitHub Enterprise Server 3.0 のリリースノートを参照してください。
- GitHub Enterprise Server 3.0以降へのアップグレードに関する詳しい情報については「GitHub Enterprise Serverのアップグレード」を参照してください。
- アップグレード後のGitHub Actionsの設定に関する詳しい情報については、GitHub Enterprise Server 3.0のドキュメンテーションを参照してください。
ノート: GitHubホストランナーは、現在GitHub Enterprise Serverでサポートされていません。 GitHubパブリックロードマップで、計画されている将来のサポートに関する詳しい情報を見ることができます。
はじめに
このガイドでは、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
ディレクトリに追加してください。 以下に示すワークフローは、リポジトリのデフォルトブランチが main
であることを前提としています。
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@v2
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のバージョンで各ジョブを設定します。 For more information about matrix strategies and contexts, see "Workflow syntax for GitHub Actions" and "Contexts."
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@v2
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@v2
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@v2
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@v2
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@v2
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@v2
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@v2
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
依存関係のキャッシングの例
When using GitHub-hosted runners, you can cache and restore the dependencies using the setup-node
action.
The following example caches dependencies for npm.
steps:
- uses: actions/checkout@v2
- uses: actions/setup-node@v2
with:
node-version: '14'
cache: 'npm'
- run: npm install
- run: npm test
The following example caches dependencies for Yarn.
steps:
- uses: actions/checkout@v2
- uses: actions/setup-node@v2
with:
node-version: '14'
cache: 'yarn'
- run: yarn
- run: yarn test
The following example caches dependencies for pnpm (v6.10+).
# このワークフローはGitHubによって認定されていないアクションを使用します。
# それらはサードパーティによって提供され、
# 別個の利用規約、プライバシーポリシー、
# サポートドキュメンテーションが適用されます。
# NOTE: pnpm caching support requires pnpm version >= 6.10.0
steps:
- uses: actions/checkout@v2
- uses: pnpm/action-setup@646cdf48217256a3d0b80361c5a50727664284f2
with:
version: 6.10.0
- uses: actions/setup-node@v2
with:
node-version: '14'
cache: 'pnpm'
- run: pnpm install
- run: pnpm test
To cache dependencies, you must have a package-lock.json
, yarn.lock
, or pnpm-lock.yaml
file in the root of the repository. If you need more flexible customization, you can use the cache
action. For more information, see "Caching dependencies to speed up workflows".
コードのビルドとテスト
ローカルで使うのと同じコマンドを、コードのビルドとテストに使えます。 たとえばpackage.jsonファイルで定義されたビルドのステップを実行するのにnpm run build
を実行し、テストスイートを実行するのにnpm test
を実行しているなら、それらのコマンドをワークフローファイルに追加します。
steps:
- uses: actions/checkout@v2
- name: Use Node.js
uses: actions/setup-node@v2
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パッケージの公開」を参照してください。