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

What’s new in V7

Migrated action internals to ESM for compatibility with latest @actions/* packages. No changes to action inputs, outputs, or behavior.

Breaking change

The dummy NODE_AUTH_TOKEN fallback has been removed, as it could unintentionally affect the generated .npmrc with a non-functional token. With this change, if registry-url is set without NODE_AUTH_TOKEN, legacy Yarn Classic (1.x) and older Node/npm versions may fail, and pnpm may warn. npm Trusted Publishing (OIDC) is not affected, since it does not use NODE_AUTH_TOKEN.

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

- uses: actions/setup-node@v7
  with:
    # Version Spec of the version to use in SemVer notation.
    # It also admits such aliases as lts/*, latest, nightly and canary builds
    # Examples: 12.x, 10.15.1, >=10.15.0, lts/Hydrogen, 16-nightly, latest, node
    node-version: ''

    # File containing the version Spec of the version to use.  Examples: package.json, mise.toml, .nvmrc, .node-version, .tool-versions.
    # If node-version and node-version-file are both provided the action will use version from node-version.
    node-version-file: ''

    # Set this option if you want the action to check for the latest available version
    # that satisfies the version spec.
    # It will only get affect for lts Nodejs versions (12.x, >=10.15.0, lts/Hydrogen).
    # Default: false
    check-latest: false

    # Target architecture for Node to use. Examples: x86, x64. Will use system architecture by default.
    # Default: ''. The action use system architecture by default
    architecture: ''

    # Used to pull node distributions from https://github.com/actions/node-versions.
    # Since there's a default, this is typically not supplied by the user.
    # When running this action on github.com, the default value is sufficient.
    # When running on GHES, you can pass a personal access token for github.com if you are experiencing rate limiting.
    #
    # We recommend using a service account with the least permissions necessary. Also
    # when generating a new PAT, select the least scopes necessary.
    #
    # [Learn more about creating and using encrypted secrets](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)
    #
    # Default: ${{ github.server_url == 'https://github.com' && github.token || '' }}
    token: ''

    # Used to specify a package manager for caching in the default directory. Supported values: npm, yarn, pnpm.
    # Package manager should be pre-installed
    # Default: ''
    cache: ''

    # Controls automatic caching for npm. By default, caching for npm is enabled if either the devEngines.packageManager field or the top-level packageManager field in package.json specifies npm and no explicit cache input is provided.
    # To disable automatic caching for npm, set package-manager-cache to false.
    # default: true
    package-manager-cache: true

    # Used to specify the path to a dependency file: package-lock.json, yarn.lock, etc.
    # It will generate hash from the target file for primary key. It works only If cache is specified.
    # Supports wildcards or a list of file names for caching multiple dependencies.
    # Default: ''
    cache-dependency-path: ''

    # Optional registry to set up for auth. Will set the registry in a project level .npmrc and .yarnrc file,
    # and set up auth to read in from env.NODE_AUTH_TOKEN.
    # Default: ''
    registry-url: ''

    # Optional scope for authenticating against scoped registries.
    # Will fall back to the repository owner when using the GitHub Packages registry (https://npm.pkg.github.com/).
    # Default: ''
    scope: ''

    # Optional mirror to download binaries from.
    # Artifacts need to match the official Node.js
    # Example:
    # V8 Canary Build: <mirror_url>/download/v8-canary
    # RC Build: <mirror_url>/download/rc
    # Official: Build <mirror_url>/dist
    # Nightly build: <mirror_url>/download/nightly
    # Default: ''
    mirror: ''

    # Optional mirror token.
    # The token will be used as a bearer token in the Authorization header
    # Default: ''
    mirror-token: ''

Basic:

steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
  with:
    node-version: 24
    package-manager-cache: false # Disable automatic npm caching if not required
- run: npm ci
- run: npm test

The node-version 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 node-version 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.

current/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 npm, yarn, pnpm (v6.10+). The cache input is optional.

The action defaults to search for the dependency file (package-lock.json, 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 node_modules

See the examples of using cache for yarn/pnpm and cache-dependency-path input in the Advanced usage guide.

Caching npm dependencies:

steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
  with:
    node-version: 24
    cache: 'npm'
- run: npm ci
- run: npm test

Caching npm dependencies in monorepos:

steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
  with:
    node-version: 24
    cache: 'npm'
    cache-dependency-path: subdir/package-lock.json
- run: npm ci
- run: npm test

Caching for npm dependencies is automatically enabled when your package.json 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 package-manager-cache input, which defaults to true. To turn off automatic caching, set package-manager-cache to false.

steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
  with:
    package-manager-cache: false
- run: npm ci

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

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [ 20, 22, 24 ]
    name: Node ${{ matrix.node }} sample
    steps:
      - uses: actions/checkout@v7
      - name: Setup node
        uses: actions/setup-node@v7
        with:
          node-version: ${{ matrix.node }}
          package-manager-cache: false # Disable automatic npm caching if not required
      - run: npm ci
      - run: npm test

Using `setup-node` on GHES

setup-node 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 token input for the action:

uses: actions/setup-node@v7
with:
  token: ${{ secrets.GH_DOTCOM_TOKEN }}
  node-version: 24
  package-manager-cache: false # Disable automatic npm caching if not required

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

Recommended permissions

When using the setup-node action in your GitHub Actions workflow, it is recommended to set the following permissions to ensure proper functionality:

permissions:
  contents: read # access to check out code and install dependencies

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