Manage GitHub GPG Keys Safely with gh gpg-key

Your signed commits show "Unverified" on GitHub, or an old key you no longer trust is still sitting on your account. gh gpg-key lists, adds and removes the GPG keys registered with your GitHub account, and it takes about ten minutes if the key already exists locally.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Check authentication before changing the account
2. List the registered keys
3. Inspect the public key you plan to add
4. Add the public key
5. Delete an obsolete key after a second check
6. Verify the final account state

This guide describes GitHub CLI 2.87.3, installed here from the gh package. The interface is small: list, add and delete.

You need: gh authenticated to the account you intend to change, plus a public GPG key for the add operation.
These commands change your GitHub account. They do not need sudo.

1. Check authentication before changing the account

Run the status check first. It is read-only and helps stop you adding a key to the wrong account or hostname:

$ gh auth status
# account and authentication details vary by login

The exact account, protocol and scopes will differ. If the check reports no active login, authenticate with gh auth login and complete its prompts. Do not paste an access token into a shell command or into this article's examples.

Checkpoint

The account named by gh auth status must be the account whose GPG keys you want to manage. Stop here if it is not.

2. List the registered keys

List the account's keys before adding anything. The result is account data, so expect the values to vary:

$ gh gpg-key list
# account-specific key records

The installed command also accepts the alias gh gpg-key ls. Use the full list spelling in scripts and runbooks, because it makes the operation obvious.

Tip

Save a key ID from this output only once you have identified the key you intend to remove. A key's email address is not its ID.

3. Inspect the public key you plan to add

gh gpg-key add takes an optional key file. Give it a public, ASCII-armoured export, never a private key. Inspect the file with GnuPG before uploading it:

$ gpg --show-keys --fingerprint /path/to/public-key.asc
# fingerprint and user ID for the selected public key

Compare the fingerprint and user ID with the identity you expect. The file should contain only public material. To make an armoured public export from a key already in your local keyring, write it to a new file:

$ gpg --export --armor KEY-ID-OR-FINGERPRINT > /tmp/github-public-key.asc
$ gpg --show-keys --fingerprint /tmp/github-public-key.asc

Replace KEY-ID-OR-FINGERPRINT with the intended key.

Warning

Keep the private key in your protected GnuPG keyring. Never use gpg --export-secret-keys for this task.

4. Add the public key

Adding a key changes your GitHub account. Once the fingerprint check passes, upload the file and optionally give it a descriptive title:

$ gh gpg-key add /path/to/public-key.asc --title "Workstation signing key"
# success or an error from GitHub CLI

The title is optional, but useful when the account has several keys. The documented input is [<key-file>]. A dash reads standard input, which saves you keeping a temporary export on disk:

$ gpg --export --armor KEY-ID-OR-FINGERPRINT | gh gpg-key add - --title "Workstation signing key"
# success or an error from GitHub CLI

A success message is not a substitute for checking the account. List the keys again and compare the new fingerprint with the local one:

$ gh gpg-key list
$ gpg --show-keys --fingerprint /path/to/public-key.asc

Recovery

If the upload fails, check that the input is a public key, the key is valid, and the authenticated account is correct. Authentication errors need a login or refreshed credentials, not sudo.

5. Delete an obsolete key after a second check

Warning

Deletion is irreversible from this command's point of view. It removes the selected key from the GitHub account, so never use a guessed or truncated identifier.

First list the keys, then copy the exact ID of the key that is revoked, expired or no longer used:

$ gh gpg-key list
$ gh gpg-key delete 0123456789ABCDEF

Answer the confirmation prompt only after checking the ID and account. The --yes option skips that prompt and suits only an automated process that has already made the selection safely:

$ gh gpg-key delete 0123456789ABCDEF --yes
# success or an error from GitHub CLI

Recovery

There is no undo flag in gh gpg-key delete. If you removed the wrong key, export the same public key from a trusted local keyring or backup and add it again, verifying its fingerprint first. Keep the private key available if you still need to create signatures, but do not upload it.

6. Verify the final account state

Finish with a fresh listing and a local fingerprint check. After an add, the fingerprint should now appear in the account. After a delete, it should be absent:

$ gh gpg-key list
$ gpg --show-keys --fingerprint /path/to/public-key.asc

A listed key does not prove that every future commit will show as verified. That depends on separate signing checks:

Matching private key. Git must sign with the private half of the registered key.
Associated email. The commit email must be associated with the GitHub account.
Valid signature. The signature itself must verify.

This command group only manages the public key registration.

Done means

Account confirmed. gh auth status names the intended GitHub account.
Before and after. You ran gh gpg-key list before and after the change.
Public key only. The uploaded material was a public key, and its fingerprint matched the local copy.
Exact ID deleted. Any deletion used an exact listed key ID and was confirmed deliberately.
Private key kept home. It stayed in the protected local keyring and was never sent to GitHub.