setup-node

This action provides the following functionality for GitHub Actions users:

• Optionally downloading and caching distribution of the requested Node.js version, and adding it to the PATH
• Optionally caching npm/yarn/pnpm dependencies
• Registering problem matchers for error output
• Configuring authentication for GPR or npm

Breaking changes in V6

• Caching is now automatically enabled for npm projects when either the

  devEngines.packageManager
  field or the top-level
  packageManager
  field in
  package.json
  is set to
  npm
  . For other package managers, such as Yarn and pnpm, caching is disabled by default and must be configured manually using the
  cache
  input.

• The

  always-auth
  input has been removed, as it is deprecated and will no longer be supported in future npm releases. To ensure your workflows continue to run without warnings or errors, please remove any references to
  always-auth
  from your configuration.

Breaking changes in V5

• Enabled caching by default with package manager detection if no cache input is provided.

  For workflows with elevated privileges or access to sensitive information, we recommend disabling automatic caching by setting

  package-manager-cache: false

  when caching is not needed for secure operation.

• Upgraded action from node20 to node24.

  Make sure your runner is on version v2.327.1 or later to ensure compatibility with this release. See Release Notes

For more details, see the full release notes on the releases page

Usage

See action.yml

Basic:

The

input is optional. If not supplied, the node version from PATH will be used. However, it is recommended to always specify Node.js version and not rely on the system one.

The action will first check the local cache for a semver match. If unable to find a specific version in the cache, the action will attempt to download a version of Node.js. It will pull LTS versions from node-versions releases and on miss or failure will fall back to the previous behavior of downloading directly from node dist.

For information regarding locally cached versions of Node.js on GitHub hosted runners, check out GitHub Actions Runner Images.

Supported version syntax

The

input supports the Semantic Versioning Specification, for more detailed examples please refer to the semver package documentation.

Examples:

• Major versions:
  22
  ,
  24
• More specific versions:
  20.19
  ,
  22.17.1
  ,
  24.8.0
• NVM LTS syntax:
  lts/iron
  ,
  lts/jod
  ,
  lts/*
  ,
  lts/-n
• Latest release:
  *
  or
  latest
  /
  current
  /
  node

Note: Like the other values,

will get the latest locally-cached Node.js version, or the latest version from actions/node-versions, depending on the

check-latest

input.

/

latest

/

node

always resolve to the latest dist version. That version is then downloaded from actions/node-versions if possible, or directly from Node.js if not. Since it will not be cached always, there is possibility of hitting rate limit when downloading from dist

Checking in lockfiles

It's strongly recommended to commit the lockfile of your package manager for security and performance reasons. For more information consult the "Working with lockfiles" section of the Advanced usage guide.

Caching global packages data

The action has a built-in functionality for caching and restoring dependencies. It uses actions/cache under the hood for caching global packages data but requires less configuration settings. Supported package managers are

,

yarn

,

pnpm

(v6.10+). The

cache

input is optional.

The action defaults to search for the dependency file (

,

npm-shrinkwrap.json

or

yarn.lock

) in the repository root, and uses its hash as a part of the cache key. Use

cache-dependency-path

for cases when multiple dependency files are used, or they are located in different subdirectories.

Note: The action does not cache

See the examples of using cache for

/

pnpm

and

cache-dependency-path

input in the Advanced usage guide.

Caching npm dependencies:

Caching npm dependencies in monorepos:

Caching for npm dependencies is automatically enabled when your

contains either

devEngines.packageManager

field or top-level

packageManager

field set to

npm

, and no explicit cache input is provided.

This behavior is controlled by the

input, which defaults to

true

. To turn off automatic caching, set

package-manager-cache

to

false

.

If your

package.json

file does not include a

packageManager

field set to

npm

, caching will be disabled unless you explicitly enable it. For workflows with elevated privileges or access to sensitive information, we recommend disabling automatic caching for npm by setting

package-manager-cache: false

when caching is not required for secure operation.

Matrix Testing

Using

setup-node

on GHES

comes pre-installed on the appliance with GHES if Actions is enabled. When dynamically downloading Nodejs distributions,

setup-node

downloads distributions from

actions/node-versions

on github.com (outside of the appliance). These calls to

actions/node-versions

are made via unauthenticated requests, which are limited to 60 requests per hour per IP. If more requests are made within the time frame, then you will start to see rate-limit errors during downloading that looks like:

##[error]API rate limit exceeded for...

. After that error the action will try to download versions directly from the official site, but it also can have rate limit so it's better to put token.

To get a higher rate limit, you can generate a personal access token on github.com and pass it as the

input for the action:

If the runner is not able to access github.com, any Nodejs versions requested during a workflow run must come from the runner's tool cache. See "Setting up the tool cache on self-hosted runners without internet access" for more information.

Advanced usage

• Check latest version
• Using a node version file
• Using different architectures
• Using v8 canary versions
• Using nightly versions
• Using rc versions
• Caching packages data
• Using multiple operating systems and architectures
• Publishing to npmjs and GPR with npm
• Publishing to npmjs and GPR with yarn
• Using private packages
• Using private mirror

Recommended permissions

When using the

action in your GitHub Actions workflow, it is recommended to set the following permissions to ensure proper functionality:

License

The scripts and documentation in this project are released under the MIT License

Contributions

Contributions are welcome! See Contributor's Guide

Code of Conduct

👋 Be nice. See our code of conduct