コンテンツへスキップ

Node.js GitHub Actions ワークフローテンプレート

最終更新

これは npm を使用する Node.js プロジェクト向けの完全な .github/workflows/ci.yml です。キャッシュから依存関係をインストールし、2 つの Node バージョンで lint、ビルド、テストを実行し、古くなったプルリクエストの実行をキャンセルします。コピーして、package.json に合わせてスクリプトを調整し、コミットしてください。

ワークフロー

name: CI

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

concurrency:
  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        node: [20, 22]
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: npm

      - run: npm ci
      - run: npm run lint --if-present
      - run: npm run build --if-present
      - run: npm test

分かりにくい部分の役割

  • permissions: contents: read により、自動生成される GITHUB_TOKEN の権限がリポジトリの読み取りに限定されます。必要な場合にのみ、ジョブごとにスコープを追加してください。
  • concurrency により、各プルリクエストに独立したグループが割り当てられます。新しいプッシュが行われると、古い実行はキャンセルされます。main へのプッシュはキャンセルされないため、main のすべてのコミットに結果が残ります。
  • timeout-minutes: 15 により、応答しないテストが既定の 6 時間まで実行され続けるのを防ぎます。通常の実行時間の約 2 倍に設定することをお勧めします。
  • fail-fast: false により、両方の Node バージョンの実行が完了するため、最初の失敗だけでなくすべての失敗を確認できます。
  • cache: npm により、setup-node は package-lock.json をキーとして、node_modules ではなく npm のダウンロードフォルダーをキャッシュします。その後、npm ci はローカルのティアボールからインストールします。詳細は GitHub Actions で npm をキャッシュする方法 を参照してください。
  • npm ci は、ロックファイルの内容どおりにインストールし、ロックファイルと不整合がある場合は失敗します。CI では npm install の代わりに使用してください。
  • --if-present は定義されていないスクリプトをスキップするため、小規模なプロジェクトでもこのテンプレートを利用できます。

バリエーション

pnpm または Yarn

キャッシュのオプションとインストールコマンドを切り替えます。pnpm の場合は、setup-node の前に pnpm/action-setup@v4 を追加し、cache: pnpm を設定します。詳しくは pnpm のキャッシュ と Yarn のキャッシュ を参照してください。

モノレポ

ビルドツール経由でタスクを実行し、リモートキャッシュを渡すと、変更のないパッケージをスキップできます。Nx と Turborepo のモノレポでの CI を参照してください。

デプロイジョブを追加

  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/deploy.sh

保存済みのキーではなく、クラウドの認証情報には OIDC を使用します。OIDC の用語集エントリーを参照してください。

macOS または Windows

os: [ubuntu-latest, macos-latest] を指定してマトリックスに追加し、runs-on: ${{ matrix.os }} を設定します。これらのプラットフォーム向けに出荷する場合にのみ使用してください。分単位の料金が高くなるためです。

より高速なマシンで実行する

テストの実行に時間がかかる場合は、1 行だけ変更し、他はそのままにしてください。

    runs-on: [self-hosted, Linux, compiler-ci]

compiler.dev は、新しい 8 vCPU / 16 GB のマシンでジョブを実行します。このマシンを利用できない場合は、元のランナーにフォールバックします。料金とGitHub Actions を高速化する方法を参照してください。

よくある質問

node_modules をキャッシュすべきですか?

通常はキャッシュしないでください。npm のダウンロードキャッシュをキャッシュし、npm ci を実行する方が安全です。node_modules にはプラットフォーム固有のバイナリが含まれる場合があり、npm ci はとにかくそれを削除するためです。

どの Node バージョンをテストすべきですか?

サポートしているアクティブな LTS 系列です。Node.js のリリーススケジュールを確認し、サポートが終了したバージョンは外してください。

テストを並列で実行するには?

ローカルではテストランナーのワーカーを使用し、複数のマシンにまたがってテストのシャーディングを行ってください。Jest と Vitest はどちらも --shard に対応しています。

キャッシュが復元されないのはなぜですか?

通常は、ロックファイルのパスが誤っているか、ブランチのスコープが異なることが原因です。キャッシュキーについて確認してください。