2026.09.28 GitHub

actions/setup-nodeとは｜v7の入力・キャッシュ設定とv5以降の既定変更

actions/setup-nodeは、GitHub ActionsのランナーへNode.jsを入れてPATHを通し、npm・yarn・pnpmの依存キャッシュまで受け持つ公式アクションです。2026年7月14日にv7.0.0が公開され、キャッシュキーを返す出力の追加と、NODE_AUTH_TOKENのダミー値の廃止が入りました。その前のv5とv6では、package.jsonの書き方しだいでキャッシュが自動で有効になる既定動作の変更も加わった形です。本記事では入力と既定値、ローカルと版を揃えるnode-version-file、キャッシュの効かせ方、npmへ公開するジョブの組み方までを、公式リポジトリの実測にもとづいて扱います。ワークフロー全体の書き方はGitHub Actionsの基本構造と使い方を解説した記事で確認できます。

まとめ：actions/setup-nodeで最初に決める版指定とキャッシュの持ち方

決めることは2つです。版はnode-version-fileで.nvmrcかpackage.jsonを読ませ、ローカルとCIの指定を1か所に寄せます。キャッシュは通常のテストジョブならcache: npmのように明示し、npmへの公開や本番デプロイのような特権ジョブではpackage-manager-cache: falseで切ります。

既存のワークフローをv7へ上げる前に確かめるのは、registry-urlを指定しているのにNODE_AUTH_TOKENを渡していないジョブの有無です。Yarn Classicや古いnpmでは、そこが失敗に変わります。セルフホストランナーを使うなら、v5以降が求めるランナーv2.327.1以上も前提条件になります。

actions/setup-nodeを動かす最小のワークフローとv7の入力一覧

まず動く形を置き、そのあとで入力と既定値を一覧で押さえます。

checkoutとsetup-nodeとnpm ciを並べる最小構成の書き方

リポジトリを取り出し、Node.jsを入れ、ロックファイルどおりに依存を入れてテストする。最小構成はこの4ステップです。

# .github/workflows/ci.yml
name: ci
on:
  pull_request:
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version-file: '.nvmrc'
          cache: 'npm'
      - run: npm ci
      - run: npm test

npm installではなくnpm ciを使う理由は、npm公式のnpm ciの説明にあるとおり、package-lock.jsonとpackage.jsonが食い違うとエラーで止まり、ロックファイルを書き換えないからです。setup-nodeより前に置くcheckoutの入力はactions/checkoutの主要入力と既定値を整理した記事で扱っています。

action.ymlで確認したv7の入力12個と出力4個の既定値

入力の定義はsetup-nodeのaction.ymlがそのまま正本です。2026年9月時点のmainブランチで、入力は12個ありました。

入力	既定値	用途
node-version	なし	版の指定
node-version-file	なし	版を書いたファイル
check-latest	false	最新パッチの確認
architecture	ランナーに従う	x64・arm64など
cache	なし	npm・yarn・pnpm
package-manager-cache	true	自動キャッシュ
cache-dependency-path	なし	ロックファイルの場所
registry-url	なし	.npmrcの生成
scope	なし	スコープ付きレジストリ
token	github.token	配布物の取得
mirror	なし	配布元の差し替え
mirror-token	なし	ミラーの認証

出力はnode-version、cache-hit、v7で増えたcache-primary-keyとcache-matched-keyの4つです。実行ランタイムはnode24で、ジョブ末尾のpost処理でキャッシュを保存します。このpost処理にはsuccess()の条件が付いており、途中のステップが失敗したジョブではキャッシュが保存されません。

Node.js本体の取得順序とcheck-latest既定falseの意味

check-latestがfalseのとき、アクションはまずランナーにキャッシュ済みの版から条件に合うものを探します。無ければactions/node-versionsのリリースから取得し、そこで取れなければnodejs.orgの配布物を直接ダウンロードする順番です。

この既定のため、node-version: 24と書いても最新パッチが入るとは限りません。ランナーイメージに入っている24系が使われます。trueにすると毎回最新を確かめに行くぶん遅くなるので、セキュリティ修正をその日のうちに取り込みたいジョブに限って使ってください。latestやcurrentの指定は常にnodejs.orgの最新版へ解決されるため、取得元のレート制限に当たる可能性があるとREADMEに記載があります。

node-versionとnode-version-fileでCIとローカルの版指定を統一

版の指定をワークフローに直書きすると、ローカルとCIで食い違ったまま気づかない状態が生まれます。

node-version-fileが読む5形式とpackage.jsonの参照順序

node-version-fileが受け付けるのは.nvmrc、.node-version、.tool-versions、mise.toml、package.jsonの5形式です。node-versionと両方書いた場合はnode-versionが勝ちます。移行途中に両方残すと、ファイルを書き換えてもCIの版が変わらない原因になります。

package.jsonを渡したときの参照順は公式のadvanced-usage.mdに明記されています。

volta.node
devEngines.runtimeのうち"name": "node"の項目
engines.node
volta.extendsで指定したファイルを辿って同じ順に探す

devEngines.runtimeの読み取りは2026年3月4日公開のv6.3.0で入りました。engines.nodeに^22 || ^24のような幅を書き、CIで使う版だけをdevEngines.runtimeで絞る書き分けができます。

lts/*や24.xなど版指定の書式とmatrixで複数版を回す例

版指定には24や24.8.0のようなSemVer表記のほか、lts/*、lts/-1、lts/jodのようなnvmと同じ別名が使えます。どのLTSをいつ選ぶかはNode.js LTSの確認と固定・移行時期を解説した記事に譲ります。

ライブラリを配布する側なら、サポート対象の版をmatrixで並べて回します。

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        node: ['22', '24', 'lts/*']
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: ${{ matrix.node }}
          cache: 'npm'
      - run: npm ci
      - run: npm test

キャッシュはNode.jsの版をまたいで共有されるため、版を3つ並べてもキャッシュ容量は3倍になりません。組み合わせの足し引きはmatrixのinclude・excludeを解説した記事が詳しいです。

cache入力とpackage-manager-cacheで依存取得を短縮する設定手順

setup-nodeのキャッシュは内部でactions/cacheを呼んでいます。何が保存されるかを知らないと、効いていないのに気づけません。

node_modulesではなくグローバルキャッシュを保存する仕組み

保存対象はnode_modulesではありません。npmならnpm config get cacheが指すグローバルキャッシュのディレクトリです。キャッシュが当たってもnpm ciは毎回走り、ネットワークからのダウンロードだけが省かれます。

キーには、リポジトリ直下のpackage-lock.json、npm-shrinkwrap.json、yarn.lockのハッシュが入ります。ロックファイルをコミットしていないリポジトリではキーが作れないため、cacheを指定せず、自動キャッシュもpackage-manager-cache: falseで止めるよう公式は案内しています。node_modulesそのものを保存したい場合や、キーを自分で設計したい場合はactions/cacheのkey設計と復元されない原因を扱った記事の範囲です。

モノレポでcache-dependency-pathを指定するキーの作り方

ロックファイルがサブディレクトリにあると、既定の探索では見つからずエラーになります。cache-dependency-pathでパスを渡してください。ワイルドカードと複数行の指定に対応しています。

      - uses: actions/setup-node@v7
        with:
          node-version-file: '.nvmrc'
          cache: 'npm'
          cache-dependency-path: |
            apps/web/package-lock.json
            apps/api/package-lock.json

複数のロックファイルを1つのキーにまとめると、どれか1つが変わっただけで全体が作り直しです。サービスごとにジョブを分けているなら、ジョブごとに自分のロックファイルだけを渡す方がヒット率は上がります。

pnpmとyarnでcacheを効かせる前にパッケージマネージャーを入れる順番

cache: pnpmはpnpm v6.10以上が対象で、setup-nodeの時点でpnpmコマンドが使えることが前提になります。そのため、pnpm/action-setupをsetup-nodeより前に置く順序が必要です。順番を逆にすると、キャッシュディレクトリの問い合わせに失敗します。

      - uses: actions/checkout@v7
      - uses: pnpm/action-setup@v6
        with:
          version: 10
      - uses: actions/setup-node@v7
        with:
          node-version-file: '.nvmrc'
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile

yarnはClassic（v1）とBerry（v2以降）の両方をキャッシュできます。pnpmの共有ストアの仕組みはpnpmの共有ストアとモノレポ運用を解説した記事で整理しています。

v5からv7で変わった既定動作と更新時に壊れる箇所の確認手順

メジャー版を上げるたびに既定の動きが変わっています。版ごとに、既存のワークフローで何が起きるかを見ていきます。

v5の自動キャッシュとnode24ランタイム・ランナーv2.327.1要件

2025年9月4日公開のv5.0.0で、cacheを書いていなくても、package.jsonにpackageManagerの記載があればキャッシュが自動で有効になりました。同時に実行ランタイムがnode20からnode24へ上がり、ランナーv2.327.1以上が必要になっています。

GitHubホステッドランナーは自動で更新されるため影響しません。セルフホストランナーやGitHub Enterprise Serverで古いランナーを固定している環境では、v5以降のsetup-nodeが起動しなくなります。先にランナーの版を確かめてください。

v6で自動キャッシュがnpm限定になった条件とalways-auth削除

2025年10月14日公開のv6.0.0で、自動キャッシュの対象はnpmだけに絞られました。条件は、devEngines.packageManagerかトップレベルのpackageManagerがnpmを指していて、cacheを明示していないことです。yarnやpnpmのプロジェクトは、v5では自動で効いていたキャッシュがv6で外れます。

v5からv6へ上げてジョブが遅くなったら、まずこれを疑ってください。cache: pnpmのように明示すれば元に戻ります。あわせて2025年12月3日公開のv6.1.0でalways-auth入力が削除されました。ワークフローに残っているalways-authは、この機会に消しておきます。

v7のNODE_AUTH_TOKENダミー廃止でYarn Classicが落ちる条件

2026年7月14日公開のv7.0.0の変更点は4つです。内部のESM移行、キャッシュキーを返す2つの出力の追加、ミラー認証の修正、そしてNODE_AUTH_TOKENのダミー値の出力をやめたことです。

影響が出るのは最後の1つです。従来はregistry-urlを指定すると、トークンを渡していなくてもダミー値が環境変数に入っていました。READMEの説明によると、v7ではregistry-urlを指定してNODE_AUTH_TOKENを渡さない構成で、Yarn Classic（1.x）や古いnpmが失敗し、pnpmは警告を出す場合があります。grep -rn "registry-url" .github/workflowsで該当ジョブを洗い出し、トークンを渡すかregistry-urlを外してから上げてください。アクションをコミットSHAで固定している場合の追随手順はGitHub ActionsのSHA固定とEnforce設定の記事にまとめています。

registry-urlとTrusted Publishingでnpm公開ジョブの設定手順

setup-nodeのregistry-urlは、プロジェクト直下に.npmrcを書き出し、認証情報を環境変数から読ませる設定です。公開ジョブではこの仕組みとキャッシュの両方に注意が要ります。

OIDCで公開するためのnpm 11.5.1要件とid-token権限

npmのTrusted Publishingを使うと、長期のnpmトークンをシークレットに置かずに、OIDCの短命トークンで公開できます。advanced-usage.mdの記載では、npm 11.5.1以上が必須で、Node.js 24以降が推奨です。

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: '24'
          registry-url: 'https://registry.npmjs.org'
          package-manager-cache: false
      - run: npm ci
      - run: npm run build --if-present
      - run: npm publish

npm側のTrusted Publisher設定と、リポジトリ・ワークフローファイル名・Environmentの組が完全に一致しないと、パッケージが存在していてもE404で失敗します。id-token: writeを含む権限の絞り方はGITHUB_TOKENの既定権限と最小権限を解説した記事を参照してください。

公開・特権ジョブでpackage-manager-cacheをfalseにする理由

上の例でpackage-manager-cache: falseを入れているのは、キャッシュ汚染への対策です。公式ドキュメントは、汚染されたキャッシュが復元されると、OIDCトークンを含む資格情報が攻撃者の制御するコードへ渡りうると説明しています。

キャッシュは同じリポジトリの別ジョブが書いたものを読みます。信頼度の低いジョブで書かれた中身を、シークレットを持つジョブで復元する経路ができるわけです。READMEも、昇格した権限や機密情報を扱うワークフローでは自動キャッシュを切るよう推奨しています。プライベートパッケージを入れるジョブでは、さらにnpm ci --ignore-scriptsでインストールスクリプトを止め、NODE_AUTH_TOKENを渡すステップを限定する書き方が示されています。

setup-nodeのキャッシュを切る場面とコンテナで版を固定する判断基準

ここは判断を言い切ります。キャッシュは入れれば速くなる設定ではなく、ジョブの権限によっては外すべき設定です。

キャッシュを切るべきジョブの権限と効果が薄いリポジトリの条件

切るべきジョブは3種類です。npmやGitHub Packagesへ公開するジョブ、本番環境の資格情報を持つデプロイジョブ、pull_request_targetのように書き込み権限付きで動くジョブ。いずれもpackage-manager-cache: falseを明示し、cacheも書きません。package.jsonにpackageManager: npmを足しただけで、書いた覚えのないキャッシュが公開ジョブで有効になるのがv6以降の既定だからです。

効果が薄いのは、依存が数十パッケージ程度でダウンロードが数秒で終わるリポジトリです。キャッシュの復元と保存にかかる時間が、省けるダウンロード時間と同程度になります。テストジョブでは使い、特権ジョブでは切る。速さが必要なら、特権ジョブ側はactions/cache/restoreで読み取りだけを行い、書き込みはテストジョブに任せる構成が公式の例に載っています。

setup-nodeを使わずコンテナイメージでNodeを固定する判断基準

本番と同じNode.jsのパッチ版でテストしなければならない案件では、setup-nodeより、ジョブのcontainer:に本番と同じイメージのダイジェストを指定する方が確実です。setup-nodeはランナーにキャッシュされた版を優先するため、同じ24指定でも実行日によってパッチ版が変わりえます。

逆に、複数の版で回すライブラリや、ランナーの起動速度を優先する社内ツールでは、setup-nodeのままで十分です。コンテナ化はイメージの取得時間ぶん毎回遅くなるため、「パッチ版の差で不具合が出た経験がある」「監査で実行環境の再現性を求められる」のどちらかに当てはまるまでは見送ってかまいません。ワークフローの権限設計から、キャッシュとデプロイの分離まで含めてCI全体を見直したい場合は、DevOps・CI/CD導入支援で設計と移行を引き受けています。

よくある質問

setup-nodeの設定で相談の多い点をまとめます。

actions/setup-nodeのcacheを指定しても速くならないのはなぜですか？

保存されるのはnpmのグローバルキャッシュで、node_modulesではないためです。キャッシュが当たってもnpm ciは毎回依存を展開し直すので、省けるのはダウンロードの時間だけです。依存が少ないリポジトリでは、キャッシュの復元と保存の時間が上回ることもあります。ログのcache-hitの出力で、実際に当たっているかを先に確かめてください。

node-versionとnode-version-fileはどちらを使うべきですか？

アプリケーションならnode-version-fileで.nvmrcかpackage.jsonを読ませる方法を勧めます。ローカルとCIの版指定が1か所にまとまり、更新漏れが起きません。複数の版で検証するライブラリはmatrixとnode-versionの組み合わせが向いています。両方を書くとnode-versionが優先される点に注意してください。

v4からv7へ一気に上げても問題ありませんか？

確認点は3つあります。セルフホストランナーがv2.327.1以上か、yarnやpnpmでcacheを明示しているか、registry-urlを使うジョブでNODE_AUTH_TOKENを渡しているか。この3点が揃っていれば、途中の版を経由する必要はありません。v5とv6で自動キャッシュの条件が変わっているため、上げた直後のジョブ時間も見比べてください。

pnpmでcache: pnpmを指定するとエラーになるのはなぜですか？

setup-nodeの実行時点でpnpmコマンドが存在しないためです。キャッシュの保存先をpnpmに問い合わせる処理が走るので、pnpm/action-setupをsetup-nodeより前のステップに置いてください。pnpmはv6.10以上が対象で、インストールはロックファイルを書き換えない–frozen-lockfileを付けて実行します。

npmへの公開ジョブでNPM_TOKENのシークレットは必要ですか？

Trusted Publishingを設定すれば不要です。permissionsにid-token: writeを与え、npm 11.5.1以上で公開すると、OIDCの短命トークンで認証されます。v7で廃止されたNODE_AUTH_TOKENのダミー値の件もTrusted Publishingには影響しません。公開ジョブではpackage-manager-cacheをfalseにして、キャッシュ経由の汚染を避けてください。