Recommended Free Tools
Reliable Node.js CI/CD starts by treating four separate things as separate: the Node.js version your application supports, the runtime used by JavaScript-based GitHub Actions, the way dependencies are installed and cached, and the credentials used to publish packages. Pinning down each one makes failures easier to diagnose and upgrades less surprising.
Why a Node.js pipeline can fail even when the app’s Node version looks right
A GitHub Actions job can select one Node.js version for your project while individual JavaScript actions run on a different embedded runtime. Changing the project’s version does not update those actions. Conversely, updating an action’s runtime does not change the Node.js version used to install, build, or test your app.
As an Amazon Associate I earn from qualifying purchases.
That distinction became especially important in 2026. GitHub’s runners began using Node 24 for JavaScript actions by default on June 16, 2026, and removed Node 20 on September 23, 2026. Users should update workflows to action releases that support Node 24; maintainers of JavaScript actions need to update the runtime their actions target. GitHub also notes that Node 24 is incompatible with macOS 13.4 and lower and lacks official ARM32 support. Those constraints concern action runtimes and runner platforms, not a blanket requirement that every application run on Node 24. GitHub’s runner-runtime changelog describes the transition.
Choose Node versions from the project’s support policy
As of October 7, 2026, the Node.js release table lists Node 24 and 22 as LTS, Node 26 as Current, and Node 20 as End-of-Life. Node.js recommends Active LTS or Maintenance LTS for production applications. Release status changes, so check the Node.js Releases page when setting or revising a workflow.
#1 Best Overall
One version or a matrix?
Use an exact Node version when the job represents the version you deploy or the version your production environment uses. Add a matrix when you need to verify a declared compatibility range. Derive its entries from the versions your project actually supports and the current Node.js release schedule; do not treat old sample matrix values in a guide as current recommendations.
A matrix can reveal a test failure confined to one supported release, but it also runs more jobs. Avoid testing releases your project does not claim to support unless you have a specific compatibility reason. Keep action runtime compatibility separate: a matrix for the application does not make an outdated JavaScript action compatible with the runner.
Rank #2
Use a lockfile-driven install in CI
For an npm project with a committed package-lock.json or npm-shrinkwrap.json, use npm ci. It installs the locked dependency versions and does not rewrite the lockfile. GitHub describes it as generally faster than npm install in its Node.js workflow guide.
Use npm install when you intend to resolve or update dependencies as part of local development and then review and commit the resulting lockfile changes. CI should normally validate the lockfile rather than silently change it. If the lockfile is missing or out of sync with package.json, fix that in development and commit the corrected file instead of relying on CI to repair it.
Rank #3
Start with a small, explicit workflow
This example selects Node 24 explicitly, installs from the npm lockfile, builds if a build script exists, and runs the test script. Change the Node version and scripts to match your production target and project configuration.
name: Node CI
on:
push:
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 24
cache: npm
- run: npm ci
- run: npm run build --if-present
- run: npm testGitHub recommends actions/setup-node because it provides consistent Node.js behavior across runners and Node versions. The action sets up the project runtime; the workflow’s other actions still need to support the runner’s JavaScript-action runtime. When making a supported-version matrix, place the matrix expression in node-version and list only the releases your project promises to support. The current GitHub guide also documents dependency caching for npm, Yarn, and pnpm.
Rank #4
Understand what dependency caching does—and does not do
Caching can reduce repeat dependency setup work, but it is a performance optimization, not a reproducibility mechanism. The lockfile and npm ci define the dependency versions; a cache should not replace either. Begin without caching if you are diagnosing an install problem, then add the package-manager cache once the install is reliable.
With actions/setup-node, setting cache: npm enables npm caching. If a cache appears stale or causes confusing behavior, remove the cache temporarily and rerun the lockfile-based install. If the failure remains, investigate the lockfile, npm configuration, registry access, or runtime rather than assuming the cache is the cause.
Publish npm packages with OIDC instead of a long-lived write token
npm trusted publishing uses OpenID Connect (OIDC) to authorize the publish operation from a configured CI workflow, avoiding a long-lived npm write token for that operation. npm currently supports GitHub Actions on GitHub-hosted runners, GitLab CI/CD on GitLab.com shared runners, and CircleCI cloud. Its requirements include npm CLI 11.5.1 or later and Node 22.14.0 or higher. A GitHub Actions workflow also needs id-token: write. Review npm’s trusted publishing documentation for the current identity and package-configuration requirements.
Trusted publishing is not a general replacement for credentials throughout the workflow. It authorizes publishing, but installing private dependencies can still require a separate read-only token. npm currently excludes self-hosted runners from trusted publishing, so a self-hosted GitHub runner does not meet this publishing setup’s stated requirements. Keep any remaining traditional tokens narrowly scoped, restrict unused tokens, and audit the package’s publisher configuration.
Quick Recap
Diagnose failures by identifying which layer changed
- Install fails only in CI: confirm the lockfile is committed and use
npm ci; check the selected Node version, npm configuration, and access to any private registry. - A JavaScript action warns about or fails on Node 20: update the workflow to a release of that action compatible with Node 24. Changing
node-versionfor the application is not the fix for an embedded action runtime. - Only one matrix entry fails: check whether that release is genuinely within the project’s supported range, then inspect runtime-specific dependency or test compatibility.
- Publishing is denied: verify the provider and runner are supported, the workflow grants
id-token: write, npm CLI and Node meet the minimum versions, and the workflow identity matches the package’s trusted-publisher configuration. - Private dependency installation fails after switching to OIDC publishing: configure separate read access for installation; publishing trust does not grant registry read permissions.
- A runner-specific failure appears: check operating system and architecture compatibility, particularly the documented Node 24 limits for older macOS and ARM32.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
