1# Node.js externals
2
3The host provides Node.js to jobs outside the image. A runner upgrade or a new Node.js version needs no image rebuild.
4
5## Builds
6
7The builds are the ones of `actions/runner`. Each archive is pinned with its SHA-256 in `internal/externals/table.go`.
8
9| Name | Node.js | Source | Architectures |
10| --- | --- | --- | --- |
11| `node20` | 20.20.2 | `nodejs.org/dist/v20.20.2/node-v20.20.2-linux-<arch>.tar.gz` | x64, arm64 |
12| `node24` | 24.21.0 | `nodejs.org/dist/v24.21.0/node-v24.21.0-linux-<arch>.tar.gz` | x64, arm64 |
13| `node20_alpine` | 20.20.2 | `github.com/actions/alpine_nodejs` release `v20.20.2` | x64 |
14| `node24_alpine` | 24.21.0 | `github.com/actions/alpine_nodejs` release `v24.21.0` | x64 |
15
16## Which Node.js an action uses
17
18- As on github.com, actions with `using: node12`, `node16` or `node20` run on `node24`.
19- `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` and `ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION` have no effect.
20- "Complete job" prints a warning that lists the actions forced from Node.js 20 to 24.
21
22## Download
23
24- `ermite-runner run` and `sandbox-check` fetch missing builds at start, in the background, into `$ERMITE_RUNNER_STATE_DIR/externals/<name>-<version>-<arch>/`.
25- Start waits for them for at most 2 minutes.
26- The SHA-256 of the `.tar.gz` is checked **before** anything is unpacked. Redirects must stay on https.
27- Extraction refuses:
28  - absolute names and `..`;
29  - devices and fifos;
30  - symbolic links that are absolute or leave the tree;
31  - entries below a link;
32  - hard links to anything but an unpacked file;
33  - archives over 200,000 entries or 2 GiB.
34- Each build is unpacked in a temporary directory and renamed into place. A directory under its final name is complete.
35- At every start, everything in `externals/` that is not a pinned build is removed.
36
37## In the sandbox
38
39Read-only, as on GitHub: `/home/runner/externals/node20/bin/node`, `node24/bin/node` and the alpine ones.
40
41| Mode | How |
42| --- | --- |
43| `container` | Read-only bind mounts of the host directories |
44| `vm` | One read-only ext4 disk, built from the set (`cache/extdisk-<key>.ext4`). Old disks are removed an hour after the last build |
45
46The set is read at every job start. A download that finishes later is used by the next job.
47
48## When a build is unavailable
49
50Causes: offline, HTTP error, wrong checksum, unsafe archive, or no build for the architecture.
51
52- The runner still runs and logs why.
53- The sandbox gets a stub `bin/node` and a file `UNAVAILABLE` with the reason.
54- A job that needs the tool fails with a message such as `node24 (Node.js 24.21.0) is not available on this runner: ...`.
55- Failures that may pass (network error, HTTP status) are retried every 5 minutes until the runner stops.
56- Other failures (wrong checksum, unsafe archive, no build for the architecture) are not retried before the next start.
57
58## Turn off
59
60`ERMITE_RUNNER_NODE=0` turns the externals off. Nothing is downloaded or attached.