chore: switch to official `release-keys` repo to verify Node.js artefacts by aduh95 · Pull Request #2415 · nodejs/docker-node

aduh95 · 2026-03-09T19:22:01Z

Description

Instead of maintaining a separate list of keys and expect to find them on public servers, let's switch to the official keyring and use the smaller gpgv tool.

Motivation and Context

https://github.com/nodejs/node?tab=readme-ov-file#verifying-binaries
nodejs/unofficial-builds#216

Testing Details

Example Output(if appropriate)

Types of changes

Documentation
Version change (Update, remove or add more Node.js versions)
Variant change (Update, remove or add more variants, or versions of variants)
Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Other (none of the above)

Checklist

My code follows the code style of this project.
My change requires a change to the documentation.
I have updated the documentation accordingly.
I have read the CONTRIBUTING.md document.
All new and existing tests passed.

nschonni · 2026-03-09T19:49:12Z

@yosifkit @tianon I think one of you had previously flagged some issues with switching to keyrings for the official images, or did I misremember that?

yosifkit · 2026-03-09T19:57:18Z

Dockerfile-alpine.template

-      { gpg --batch --keyserver keyserver.ubuntu.com --recv-keys "$key" && gpg --batch --fingerprint "$key"; } ; \
-    done \
+    && export PUBRING="$(mktemp)" \
+    && curl -fsSLo "$PUBRING" --compressed https://github.com/nodejs/release-keys/raw/HEAD/gpg-only-active-keys/pubring.kbx \


Just like any file downloaded in the Dockerfile, this would need to be verified by a sha256sum embedded in the Dockerfile (at a minimum) in order to be acceptable to Docker Official Images. See https://github.com/docker-library/official-images/tree/3b4779967d1c2e369aeae1c8533d12f5a9b4df81#image-build.

In many instances, we also recommend checking that only the expected keys exist in the keyring (or maybe that was only when adding them to an apt keyring). cc @tianon

The content of the keyring is validated in https://github.com/nodejs/release-keys/actions/runs/20075780501/workflow#L64, do you know if that's good enough?

I've added a step that checks the pubring only contains the expected keys, PTAL

yosifkit · 2026-03-09T19:58:11Z

@yosifkit @tianon I think one of you had previously flagged some issues with switching to keyrings for the official images, or did I misremember that?

I think you might be referring to #1509 (comment)

update.sh

nschonni · 2026-03-09T20:10:26Z

Maybe there is a way in the middle, where the script grabs and parses the keyring, but the image keeps the valid/current keys embedded in the Dockerfile we send upstream

tianon · 2026-03-09T22:17:55Z

I think you might be referring to #1509 (comment)

That's the one that's most directly pertinent to docker-node -- see also nodejs/node#58979 (comment), nodejs/node#58904 (comment), nodejs/node#39227 (comment) 😅

tianon · 2026-03-11T18:44:34Z

I think you might be referring to #1509 (comment)

That's the one that's most directly pertinent to docker-node -- see also nodejs/node#58979 (comment), nodejs/node#58904 (comment), nodejs/node#39227 (comment) 😅

To quote nodejs/node#58979 (comment):

"Just trust this precompiled binary bundle of key data" is not exactly something that fills me with warm fuzzies 😅 -- how would I, as a user, verify the contents of pubring.kbx? How would I know which parts of it are relevant for a given Node.js release?

And nodejs/node#39227 (comment):

IMO, https://github.com/nodejs/release-keys would be a very interesting place to include a bit more (programmatically accessible such as symlinks in folders or a JSON doc) metadata about how the keys related to releases, such as which are expected to be actively signing new releases of each version track vs which keys have been used historically to sign releases for each track and aren't expected to sign new releases (instead of just a big bundle of keys for everyone both past and present).

Having that sort of metadata/organization would make something like #1511 much easier to implement, but would also generally reduce the possibility of something like an outdated key being compromised creating a worry for new releases. 👀

As it stands, https://github.com/nodejs/release-keys is functionally not much different from the KEYS files that are common in Apache projects, albeit with some added scaffolding to help ease consumption. 😅

See also https://github.com/docker-library/faq#how-can-i-use-a-keys-file-for-verifying-pgp-signatures

Copilot

Pull request overview

Updates the Node.js artifact verification flow in this repo’s generated Dockerfiles to use the official nodejs/release-keys keyring (downloaded + SHA256-pinned) and gpgv, replacing the prior per-key keyserver fetch approach.

Changes:

Replace Node.js keyserver-based key fetching with a pinned pubring.kbx keyring download + SHA256 verification, and verify SHASUMS256.txt.asc with gpgv.
Update the key update workflow to persist the resolved keyring URL and its SHA256 to keys/.
Remove the legacy keys/node.keys list and update Dockerfile generation accordingly.

Reviewed changes

Copilot reviewed 40 out of 40 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
update.sh	Stops injecting `NODE_KEYS` and instead injects Yarn keys plus Node.js keyring URL/hash into generated Dockerfiles.
update-keys.sh	Updates the workflow to resolve the official Node.js keyring URL and store its SHA256 for pinning.
keys/nodejs.url	Stores the resolved/pinned `release-keys` raw URL for `pubring.kbx`.
keys/nodejs.shasum	Stores the SHA256 checksum line used to validate the downloaded `pubring.kbx`.
keys/node.keys	Removes the legacy list of individual Node.js release key fingerprints.
Dockerfile-slim.template	Switches Node verification to `gpgv` + keyring download/sha256 validation.
Dockerfile-debian.template	Switches Node verification to `gpgv` + keyring download/sha256 validation.
Dockerfile-alpine.template	Switches Node verification to `gpgv` + keyring download/sha256 validation (source-build path).
25/trixie/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 25 on trixie.
25/trixie-slim/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 25 slim on trixie.
25/bullseye/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 25 on bullseye.
25/bullseye-slim/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 25 slim on bullseye.
25/bookworm/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 25 on bookworm.
25/bookworm-slim/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 25 slim on bookworm.
25/alpine3.23/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 25 on alpine3.23 (source-build path).
25/alpine3.22/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 25 on alpine3.22 (source-build path).
24/trixie/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 24 on trixie.
24/trixie-slim/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 24 slim on trixie.
24/bullseye/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 24 on bullseye.
24/bullseye-slim/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 24 slim on bullseye.
24/bookworm/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 24 on bookworm.
24/bookworm-slim/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 24 slim on bookworm.
24/alpine3.23/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 24 on alpine3.23 (source-build path).
24/alpine3.22/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 24 on alpine3.22 (source-build path).
22/trixie/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 22 on trixie.
22/trixie-slim/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 22 slim on trixie.
22/bullseye/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 22 on bullseye.
22/bullseye-slim/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 22 slim on bullseye.
22/bookworm/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 22 on bookworm.
22/bookworm-slim/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 22 slim on bookworm.
22/alpine3.23/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 22 on alpine3.23 (source-build path).
22/alpine3.22/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 22 on alpine3.22 (source-build path).
20/trixie/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 20 on trixie.
20/trixie-slim/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 20 slim on trixie.
20/bullseye/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 20 on bullseye.
20/bullseye-slim/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 20 slim on bullseye.
20/bookworm/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 20 on bookworm.
20/bookworm-slim/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 20 slim on bookworm.
20/alpine3.23/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 20 on alpine3.23 (source-build path).
20/alpine3.22/Dockerfile	Applies the new `gpgv` + keyring verification flow for Node 20 on alpine3.22 (source-build path).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Dockerfile-debian.template

25/trixie/Dockerfile

Dockerfile-slim.template

Dockerfile-alpine.template

update-keys.sh

25/trixie/Dockerfile

aduh95 changed the title ~~chore: switch to official release-keys repo to verify Node.js~~ chore: switch to official release-keys repo to verify Node.js artefacts Mar 9, 2026

yosifkit reviewed Mar 9, 2026

View reviewed changes

nschonni reviewed Mar 9, 2026

View reviewed changes

update.sh Outdated Show resolved Hide resolved

This comment was marked as outdated.

Sign in to view

MikeMcC399 mentioned this pull request Mar 10, 2026

Migrate to Node.js verification using keyring source #2265

Closed

aduh95 linked an issue Mar 10, 2026 that may be closed by this pull request

Migrate to Node.js verification using keyring source #2265

Closed

PeterDaveHello requested a review from Copilot March 26, 2026 01:51

Copilot started reviewing on behalf of PeterDaveHello March 26, 2026 01:52 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

aduh95 added 12 commits March 26, 2026 16:12

chore: switch to official release-keys repo to verify Node.js

c90d8a9

squash! no pipefail

9cce837

fixup! squash! no pipefail

4fb4724

fixup! squash! no pipefail

416fb8b

squash! fix file name

8334374

fixup! squash! fix file name

0f084ba

squash! somehow trixie does not have gpgv

327e93c

fixup! squash! somehow trixie does not have gpgv

4d29191

fixup! squash! somehow trixie does not have gpgv

76b0b22

squash! remove duplicate set -ex

5082131

squash! update keyring

619a4d1

squash! address code reviews

a3d6947

aduh95 force-pushed the official-keys branch from 34b1221 to a3d6947 Compare March 26, 2026 15:12

aduh95 added 3 commits March 26, 2026 16:16

squash! remove temp files

9f29b07

squash! move the pubring check inside the Dockerfile

1c999e8

squash! shellcheck

70d5ba1

aduh95 added 12 commits March 26, 2026 17:14

fixup! squash! move the pubring check inside the Dockerfile

754cbb9

squash! fix typo

fa4b140

squash! use printf to get a reliable result

93098e1

fixup! squash! use printf to get a reliable result

7d9a460

squash! don't sort, filter out env specific value

9f6569a

squash! only check for fingerprints

6a15424

squash! move back to nodejs.keys

daac274

fixup! squash! move back to nodejs.keys

4465008

fixup! squash! move back to nodejs.keys

6d09498

fixup! squash! move back to nodejs.keys

c63cbda

fixup! squash! move back to nodejs.keys

c08988f

fixup! squash! move back to nodejs.keys

fc4d9bd

Conversation

aduh95 commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and Context

Testing Details

Example Output(if appropriate)

Types of changes

Checklist

Uh oh!

nschonni commented Mar 9, 2026

Uh oh!

yosifkit Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

aduh95 Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

aduh95 Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

yosifkit commented Mar 9, 2026

Uh oh!

Uh oh!

nschonni commented Mar 9, 2026

Uh oh!

tianon commented Mar 9, 2026

Uh oh!

This comment was marked as outdated.

tianon commented Mar 11, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

aduh95 commented Mar 9, 2026 •

edited

Loading