Skip to content

docs: Update provenance guide for modern GnuPG keybox/armored keyring verification #2162

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

Draft
promptless-for-oss wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: Update provenance guide for modern GnuPG keybox/armored keyring verification #2162

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
11 changes: 7 additions & 4 deletions docs/topics/provenance.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,12 +59,15 @@ key's `uid` (in the output of `gpg --list-keys`), for example the name or email.
**TIP:** for GnuPG users, your secret keyring is in `~/.gnupg/secring.gpg`. You
can use `gpg --list-secret-keys` to list the keys you have.

**Warning:** the GnuPG v2 store your secret keyring using a new format `kbx` on
the default location `~/.gnupg/pubring.kbx`. Please use the following command
to convert your keyring to the legacy gpg format:
**Note:** Since GnuPG v2.1, public keys are stored in a keybox file

@promptless-for-oss promptless-for-oss Jul 2, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Rewrote the note based on PR #32281, which makes loadKeyRing (pkg/provenance/sign.go) format-aware so verification auto-detects keybox (pubring.kbx), ASCII-armored (gpg --export --armor), and legacy binary keyrings — removing the need to convert to pubring.gpg. defaultKeyring() in pkg/cmd/dependency_build.go now falls back to pubring.kbx. The PR scope is public-keyring reads (verification) only; the --sign secret-key path is unchanged, so the guidance to export a binary secret keyring for signing stays.

Source: helm/helm#32281

(`~/.gnupg/pubring.kbx`) rather than the legacy `~/.gnupg/pubring.gpg`. For
verification, Helm reads the keybox format directly, along with ASCII-armored
public keyrings (`gpg --export --armor`) and the legacy binary keyring, so no
conversion is required. Signing a chart is different: Helm still needs the
private key in a binary secret keyring file. If your secret key exists only in
GnuPG's modern key store, export it first:

```console
$ gpg --export >~/.gnupg/pubring.gpg
$ gpg --export-secret-keys >~/.gnupg/secring.gpg
```

Expand Down
Loading