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モノレポを高速化するに記載しています。
よくある間違い
- ref
origin/mainがありません。 フィルターが何も見つけないか、すべてを見つけてしまいます。 - 依存元を忘れる。
[origin/main]を...なしで使うと、依存関係を通じて影響を受けたパッケージがスキップされます。 - インストールをフィルターする。 各ジョブが一部のみを必要とすることが確実な場合にのみ、インストールをフィルターしてください。依存関係の漏れは、分かりにくいエラーとして現れます。
- ルートレベルの変更。
pnpm-lock.yamlやルートの設定の変更は、すべてのパッケージに影響します。これらが変更された場合は、全テストの実行を検討してください。
よくある質問
pnpmはどのようにパッケージが変更されたと判断するのですか?
基準となるrefからのgit diffを、パッケージのディレクトリに対応付けることで判断します。また、pnpm-workspace.yaml内で使用しているcatalogのバージョンが変更された場合も、そのパッケージは変更されたとみなされます。
pnpmのフィルターをTurborepoと一緒に使えますか?
はい。ただし、Turborepoにも類似の構文を持つ独自の--filterがあります。コマンドごとにどちらか一方を使用してください。
pnpm install --filterは安全ですか?
matrixで少数のジョブを使う場合には安全です。迷ったら全体をインストールしてください。キャッシュされたストアがあれば、コストは小さく済みます。
どのfetch-depthを使うべきですか?
0が安全です。ベースブランチのシャロー取得も、マージベースをカバーしていれば機能します。
関連記事
- GitHub Actionsでpnpmの依存関係をキャッシュするpnpm/action-setup、setup-node、actions/cacheを使い、GitHub Actionsでpnpmストアをキャッシュします。ストアのパス、キー、ワークスペース、キャッシュヒットの確認方法を解説します。
- GitHub ActionsでBazelモノレポを最速でCIするGitHub Actions での高速な Bazel CI。影響を受けるビルドのためのターゲット判定、リモートキャッシュのフラグ、PR からの読み取り専用アップロード、シャーディング、完全なワークフローを紹介します。
- GitHub ActionsでNxモノレポを最速でCIするGitHub Actions で Nx の CI を高速化。nx-set-shas を使った nx affected、Nx リモートキャッシュ、タスク分散、fetch-depth、完全なワークフローを紹介します。
- GitHub ActionsでTurborepoモノレポを最速でCIするGitHub ActionsでのTurborepo CIを高速化。変更されたパッケージ向けの--filter、TURBO_TOKENを使ったリモートキャッシュ、fetch-depth、シャーディング、完全なワークフロー。