actions/setup-node installs and configures Node.js for GitHub Actions

What actions/setup-node does in a GitHub Actions workflow

The actions/setup-node action provides a small set of functions for GitHub Actions users who need a Node.js toolchain in their workflow. According to its README, it can optionally download and cache the distribution of the requested Node.js version and add it to the PATH. It can also optionally cache npm, yarn, or pnpm dependencies, register problem matchers for error output, and configure authentication for GitHub Packages Registry or npm.

The node-version input is optional. If you do not supply it, the action uses whatever Node.js version is already on the PATH. The README recommends that you always specify the version you want rather than relying on the system one, because the default can change between runner images.

When the action runs, it first checks the local cache for a SemVer match. If it cannot find the specific version cached, it attempts to download a copy of Node.js. It pulls LTS versions from the actions/node-versions releases, and on a miss or failure it falls back to downloading directly from the official Node.js distribution site.

A basic workflow that runs your tests

A typical setup pairs actions/checkout with actions/setup-node, then runs your package scripts. The example below pins the Node version to 24 and turns off automatic npm caching because the project does not need it.

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

After setup, the workflow runs npm ci to install from the lockfile and npm test to execute the suite. Because setup-node placed the chosen Node version on the PATH, both commands run against that version.

Caching dependencies for npm, yarn, and pnpm

The action has built-in support for caching and restoring dependencies. Under the hood it uses actions/cache to cache global package data, but it needs far less configuration than wiring up actions/cache by hand. The supported package managers are npm, yarn, and pnpm (version 6.10 or later), and the cache input is optional.

By default the action looks for a dependency file such as package-lock.json, npm-shrinkwrap.json, or yarn.lock in the repository root, and it uses that file's hash as part of the cache key. It is worth noting that the action does not cache node_modules itself; it caches the global package data instead.

For npm projects, automatic caching is enabled when your package.json sets either the devEngines.packageManager field or the top-level packageManager field to npm and you do not pass an explicit cache input. This behavior is controlled by the package-manager-cache input, which defaults to true. To switch it off you set package-manager-cache to false.

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

The Node.js version syntax you can request

The node-version input follows the Semantic Versioning specification. You can ask for a major version such as 22 or 24, a more specific version such as 20.19 or 22.17.1, or an NVM style LTS alias such as lts/iron, lts/jod, or lts/*. You can also request the latest release with * or with latest, current, or node.

The values latest, current, and node always resolve to the newest distribution version, which the action then downloads from actions/node-versions if possible, or directly from Node.js if not. A separate node-version-file input lets you point at a file that carries the version, such as package.json, mise.toml, .nvmrc, .node-version, or .tool-versions. If both node-version and node-version-file are given, node-version wins.

What changed across versions 5, 6, and 7

Version 7 migrated the action's internals to ESM for compatibility with the latest @actions/* packages. The README states there are no changes to action inputs, outputs, or behavior. The one breaking change is the removal of the dummy NODE_AUTH_TOKEN fallback, which could quietly affect the generated .npmrc with a non-functional token. After this change, setting registry-url without NODE_AUTH_TOKEN may break legacy Yarn Classic 1.x and older Node or npm, and pnpm may warn, while npm Trusted Publishing (OIDC) is unaffected because it does not use that token.

Version 6 turned on caching automatically for npm projects when the packageManager field names npm, and it removed the deprecated always-auth input. Version 5 enabled caching by default with package manager detection when no cache input was given, and it upgraded the action from node20 to node24, which requires the runner to be on version 2.327.1 or later. For workflows with elevated privileges or sensitive data, the README recommends disabling automatic caching by setting package-manager-cache to false.

Running on GitHub Enterprise Server and setting permissions

On GitHub Enterprise Server, setup-node ships pre-installed on the appliance when Actions is enabled. When it needs to download Node distributions, it pulls them from actions/node-versions on github.com through unauthenticated requests, which are limited to 60 per hour per IP. Once that limit is hit you will see rate-limit errors, so the README suggests passing a personal access token through the token input to raise the ceiling. If the runner cannot reach github.com, the requested Node versions must already live in the runner's tool cache.

For routine use the README recommends a minimal permissions block containing only contents: read. The project itself is released under the MIT license, and contributions are accepted through the contributor's guide and a code of conduct.

Editorial conclusion

actions/setup-node is a focused GitHub Action that gives workflows a predictable Node.js toolchain: it downloads and caches the version you request, places it on the PATH, and optionally caches your package manager dependencies. Recent releases have pushed the internals to ESM and made npm caching automatic, while keeping the inputs stable. Whether you run a single version, a test matrix, or an enterprise server behind a firewall, the action handles version selection, caching, and authentication so your npm, yarn, or pnpm steps run against the Node.js you intended.

Frequently asked questions

Official sources

1. actions/setup-node on GitHub
2. Issues
3. License: MIT
4. README
5. Releases