Skip to content

doc: update the instruction on how to verify releases #59113

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
+19 −23
Open

doc: update the instruction on how to verify releases #59113

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
49d0a1e
doc: update the instruction on how to verify releases
aduh95 Jul 18, 2025
5609491
Update README.md
aduh95 Jul 19, 2025
292089f
Apply suggestions from code review
aduh95 Jul 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 19 additions & 23 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,37 +95,27 @@ _docs_ subdirectory. Version-specific documentation is also at

### Verifying binaries

Download directories contain a `SHASUMS256.txt` file with SHA checksums for the
files.
Download directories contain a `SHASUMS256.txt.asc` file with SHA checksums for the
files and the releaser PGP signature.

To download `SHASUMS256.txt` using `curl`:
You can get a trusted keyring from nodejs/release-keys, e.g. using `curl`:

```bash
curl -O https://nodejs.org/dist/vx.y.z/SHASUMS256.txt
curl -fsLo "/path/to/nodejs-keyring.kbx" "https://github.com/nodejs/release-keys/raw/HEAD/gpg/pubring.kbx"
```

To check that downloaded files match the checksum, use `sha256sum`:
Alternatively, you can import the releaser keys in your default keyring, see
[Release keys](#release-keys) for commands to how to do that.
Comment on lines +107 to +108
Copy link

@MikeMcC399 MikeMcC399 Jul 19, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The release keys section only contains commands to import individual keys from the gpg-only-active-keys set, so it is not a substitute for importing from /gpg/pubring.kbx. There are no commands listed for keys in the section "Other keys used to sign some previous releases".

Maybe say here something like "you can import only the primary PGP releaser keys ..."

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I made a related proposal in nodejs/release-keys#48 to have a keyring for supported releases only. That would make it simpler here. At the moment it would be out-of-scope for this PR which needs to deal with the keyrings as they are currently available.


```bash
sha256sum -c SHASUMS256.txt --ignore-missing
```

For Current and LTS, the GPG detached signature of `SHASUMS256.txt` is in
`SHASUMS256.txt.sig`. You can use it with `gpg` to verify the integrity of
`SHASUMS256.txt`. You will first need to import
[the GPG keys of individuals authorized to create releases](#release-keys).

See [Release keys](#release-keys) for commands to import active release keys.

Next, download the `SHASUMS256.txt.sig` for the release:
Then, you can verify the files you've downloaded locally
(if you're using your default keyring, pass `--keyring="${GNUPGHOME:-~/.gnupg}/pubring.kbx"`):

```bash
curl -O https://nodejs.org/dist/vx.y.z/SHASUMS256.txt.sig
curl -fsO "https://nodejs.org/dist/${VERSION}/SHASUMS256.txt.asc" \
&& gpgv --keyring="/path/to/nodejs-keyring.kbx" --output SHASUMS256.txt < SHASUMS256.txt.asc \
&& shasum --check SHASUMS256.txt --ignore-missing
```

Then use `gpg --verify SHASUMS256.txt.sig SHASUMS256.txt` to verify
the file's signature.

## Building Node.js

See [BUILDING.md](BUILDING.md) for instructions on how to build Node.js from
Expand Down Expand Up @@ -806,8 +796,11 @@ Primary GPG keys for Node.js Releasers (some Releasers sign with subkeys):
* **Ulises Gascón** <<[email protected]>>
`A363A499291CBBC940DD62E41F10027AF002F8B0`

To import the full set of trusted release keys (including subkeys possibly used
to sign releases):
You can use the keyring the project maintains at
<https://github.com/nodejs/release-keys/raw/refs/heads/main/gpg-only-active-keys/pubring.kbx>.
Alternatively, you can import them from a public key server. Have in mind that
the project cannot guarantee the availability of the server nor the keys on
that server.

```bash
gpg --keyserver hkps://keys.openpgp.org --recv-keys 5BE8A3F6C8A5C01D106C0AD820B1A390B168D356 # Antoine du Hamel
Expand Down Expand Up @@ -867,6 +860,9 @@ verify a downloaded file.
* **Timothy J Fontaine** <<[email protected]>>
`7937DFD2AB06298B2293C3187D33FF9D0246406D`

The project maintains a keyring able to verify all past releases of Node.js at
<https://github.com/nodejs/release-keys/raw/refs/heads/main/gpg/pubring.kbx>.

</details>

### Security release stewards
Expand Down