setup-node-action

Install Node.js on Forgejo Actions runners from the official distribution (or a mirror you choose), and cache npm/pnpm/yarn through rasterstate/cache-action. A port of actions/setup-node with no GitHub toolcache assumptions and no PAT. Composite action, pure shell, no build step.

Quick start

jobs:
  build:
    runs-on: [self-hosted, Linux]
    env:
      # Only needed if you use cache: (it drives the nested cache-action).
      RASTER_CACHE_S3_BUCKET: ci-cache
      RASTER_CACHE_S3_ENDPOINT: https://fsn1.your-objectstorage.com
      RASTER_CACHE_S3_REGION: fsn1
      RASTER_CACHE_S3_ACCESS_KEY_ID: ${{ secrets.CACHE_S3_KEY_ID }}
      RASTER_CACHE_S3_SECRET_ACCESS_KEY: ${{ secrets.CACHE_S3_SECRET }}
    steps:
      - uses: actions/checkout@v6
      - uses: https://rasterhub.com/rasterstate/setup-node-action@v1
        with:
          node-version: '20'
          cache: npm
      - run: npm ci
      - run: npm test

Inputs

Mirror actions/setup-node.

Input	Default	Description
node-version		Exact (20.11.1), major (20), major.minor (20.11), latest, lts, or lts/<codename>.
node-version-file		Path to a .nvmrc / .node-version. Auto-detected if neither input is set.
architecture	runner arch	x64 or arm64.
cache		npm, pnpm, or yarn. Empty disables caching.
cache-dependency-path	manager lockfile	Lockfile path(s) to hash, one per line.
registry-url		Registry URL to write into .npmrc.
scope		@org for the registry.
always-auth	false	Set always-auth in .npmrc.
node-mirror	https://nodejs.org/dist	Distribution base URL (point at a mirror for air-gapped runners).

Outputs

Output	Description
node-version	Resolved version installed (with leading v).
cache-hit	Exact cache match (empty when cache is disabled).

How it works

• Install: resolves the version against the official index.tab, downloads the node-vX-os-arch.tar.gz, verifies it against SHASUMS256.txt, and installs into the runner tool cache ($RUNNER_TOOL_CACHE/node/<ver>/<arch>, reused across jobs). No GitHub API or GitHub Releases.
• Cache: when cache: is set, a step computes the manager's cache directory and a lockfile-hash key, then a nested rasterstate/cache-action step restores it and saves it in the job's post step. This needs a configured cache backend (RASTER_CACHE_*).
• Registry: when registry-url is set, writes .npmrc with a literal ${NODE_AUTH_TOKEN} auth line (set NODE_AUTH_TOKEN in your publish step's env).

Private registries

- uses: https://rasterhub.com/rasterstate/setup-node-action@v1
  with:
    node-version: '20'
    registry-url: https://npm.your-host.com
    scope: '@your-org'
- run: npm publish
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Version resolution scope

Exact, major, major.minor, latest, lts, and lts/<codename> are supported. Complex semver ranges (">=18 <21") are not; pin a concrete spec. See MIGRATION.md.

Examples

See examples/workflows.

License

MIT. See LICENSE.