コンテンツへスキップ

GitHub ActionsでpnpmワークスペースのCIを最速化する

最終更新 · 初回公開

pnpmのワークスペースでは、追加のツールを使わなくても、ビルドシステムの高速化の大部分を実現できます。pnpmストアをキャッシュし、インストールを一度だけ行い、pnpm --filter "...[origin/main]"で変更されたパッケージに対してのみスクリプトを実行します。このガイドでは、そのためのフィルターとチェックアウトの設定を解説し、TurborepoやNxを追加すべきかどうかについても説明します。

一度だけインストールし、ストアをキャッシュする

steps:
  - uses: actions/checkout@v6
    with:
      fetch-depth: 0
  - uses: pnpm/action-setup@v6
  - uses: actions/setup-node@v7
    with:
      node-version: 22
      cache: pnpm
  - run: pnpm install --frozen-lockfile

リポジトリのルートでインストールします。pnpmは一度の処理で、すべてのワークスペースパッケージをインストールしてリンクします。ストアのパスやキーの詳細はGitHub Actionsでpnpmをキャッシュhoweverをご覧ください。

変更されたパッケージのみを実行する

pnpmの--filterは、変更を基準とするセレクターを受け付けます。pnpmのフィルタリングドキュメント(2026年10月確認)より:

# packages changed since origin/main
pnpm --filter "[origin/main]" test

# changed packages plus everything that depends on them
pnpm --filter "...[origin/main]" test

# changed packages plus their dependencies
pnpm --filter "[origin/main]..." build

CIでのtestやbuildには"...[origin/main]"を使用します。packages/uiの変更は、それに依存するapps/webのテストを再実行する必要があります。セレクターの前にある...は、依存元のパッケージを追加します。

同じドキュメントにある、役立つオプションが2つあります。

  • --test-pattern="test/*"は、テストファイルのみが変更された場合に依存元の追加を止めるため、テストの編集によって全体が再テストされることがありません。
  • --changed-files-ignore-pattern="**/README.md"は、ドキュメントなど影響のない変更を無視します。
pnpm --filter "...[origin/main]" \
  --changed-files-ignore-pattern="**/*.md" \
  run test

同じドキュメントによると、基準となるrefはマージベース(ブランチが分岐したコミット)と比較されます。マージベースがないシャロークローンでは、pnpmはrefを直接比較します。セレクターにはGit 2.24以降が必要です。GitHubホストのイメージおよびcompiler.devのイメージには、より新しいGitが含まれています。

Fetch-depth

origin/mainがローカルに存在している必要があります。チェックアウトはPRのマージコミットのみを取得するため、ベースブランチのrefが存在しない場合があります。解決方法は2つあります。

- uses: actions/checkout@v6
  with:
    fetch-depth: 0

または、必要な分だけを取得します。

- uses: actions/checkout@v6
  with:
    fetch-depth: 1
- run: git fetch --no-tags --depth=200 origin ${{ github.base_ref }}

200コミットでマージベースをカバーできる場合はシャロー取得も機能します。そうでない場合、結果の精度は下がります。履歴全体を取得するのが最も簡単で、チェックアウトでfilter: tree:0を指定すれば、それでも高速です。

mainへのpushイベントでは、origin/mainが現在のコミットを指すため、フィルターは何も選択しません。pushには"...[HEAD^1]"を使うか、mainでは全テストを実行し、フィルター付きの実行はPRのみに限定してください。

pnpm内での並列化

pnpmは依存関係の順序(トポロジカル順)でスクリプトを実行し、並列化することもできます。-rを使う例:

pnpm -r --workspace-concurrency=8 run test

--workspace-concurrencyのデフォルトは4です。8コアのマシンでは、8から始めるのが妥当です。フィルターと組み合わせる例:

pnpm --filter "...[origin/main]" --workspace-concurrency=8 run test

スクリプトが存在しないパッケージで失敗しないように、--if-presentを付けて実行してください。実行順序の問題をデバッグする場合にのみ、--workspace-concurrency=1を使用してください。

複数のジョブへの分割

pnpmは、作業を複数のマシンに分散しません。パッケージまたはタスクグループごとに、GitHubのmatrixを使用してください。

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        package: [web, api, worker]
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v6
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile --filter "${{ matrix.package }}..."
      - run: pnpm --filter "${{ matrix.package }}" test

pnpm install --filterとname...を組み合わせると、そのパッケージとその依存関係だけをインストールするため、各ジョブが短縮されます。名前の後ろのドット は依存関係を、名前の前のドット(...name)は依存元、つまりそれに依存するパッケージを意味します。特定のジョブだけが長くならないよう、matrixのバランスを取ってください。単一の大きなテストスイートを分割する方法はテストのシャーディングを、何シャードにすると効果的かはシャード計算ツールをご覧ください。

TurborepoやNxを追加するタイミング

pnpmのフィルターは、どのパッケージが変更されたかを示しますが、タスクの出力はキャッシュしません。同じパッケージがPRごとにゼロから再ビルドされる場合は、タスクキャッシュが有効です。TurborepoとNxは入力をハッシュ化し、出力を再生します。ローカルでもリモートでも動作します。詳しくはTurborepo向けの最速CIとNx向けの最速CIをご覧ください。どちらもpnpmワークスペースの上で問題なく動作し、pnpm-workspace.yamlのpackagesグロブをそのまま使用します。

完全なワークフロー

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

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  check:
    runs-on: [self-hosted, Linux, compiler-ci]   # or ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v6
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - name: PR: changed packages only
        if: github.event_name == 'pull_request'
        run: |
          pnpm --filter "...[origin/${{ github.base_ref }}]" \
            --workspace-concurrency=8 run --if-present lint test build
      - name: main: everything
        if: github.event_name == 'push'
        run: pnpm -r --workspace-concurrency=8 run --if-present lint test build

concurrencyブロックは、同じブランチで置き換えられた実行をキャンセルするため、分数の節約にもつながります。詳しくはGitHub Actionsの請求額を削減するをご覧ください。compiler.devでは、runs-onの行で、依存関係のキャッシュを備えた8 vCPUのマシン上でジョブが実行されます。料金は1分あたり$0.008です。詳しくは料金をご覧ください。

TypeScriptのモノレポでは、型チェックとリントが遅い原因になることがよくあります。それらのキャッシュ方法はTypeScriptモノレポを高速化するに記載しています。

よくある間違い

  1. ref origin/main がありません。 フィルターが何も見つけないか、すべてを見つけてしまいます。
  2. 依存元を忘れる。 [origin/main]を...なしで使うと、依存関係を通じて影響を受けたパッケージがスキップされます。
  3. インストールをフィルターする。 各ジョブが一部のみを必要とすることが確実な場合にのみ、インストールをフィルターしてください。依存関係の漏れは、分かりにくいエラーとして現れます。
  4. ルートレベルの変更。 pnpm-lock.yamlやルートの設定の変更は、すべてのパッケージに影響します。これらが変更された場合は、全テストの実行を検討してください。

よくある質問

pnpmはどのようにパッケージが変更されたと判断するのですか?

基準となるrefからのgit diffを、パッケージのディレクトリに対応付けることで判断します。また、pnpm-workspace.yaml内で使用しているcatalogのバージョンが変更された場合も、そのパッケージは変更されたとみなされます。

pnpmのフィルターをTurborepoと一緒に使えますか?

はい。ただし、Turborepoにも類似の構文を持つ独自の--filterがあります。コマンドごとにどちらか一方を使用してください。

pnpm install --filterは安全ですか?

matrixで少数のジョブを使う場合には安全です。迷ったら全体をインストールしてください。キャッシュされたストアがあれば、コストは小さく済みます。

どのfetch-depthを使うべきですか?

0が安全です。ベースブランチのシャロー取得も、マージベースをカバーしていれば機能します。

このモノレポのビルドをcompiler.devで実行 カード登録不要 · 200 無料分

無料で試す