Home / Alt manpages / gh-gpg-key(1)

  • gh-gpg-key(1)
  • User command
  • linux

Manage GitHub GPG Keys Safely with gh gpg-key

You will list the GPG keys registered with your GitHub account, add a public key from an ASCII-armoured file or standard input, and remove an obsolete key after checking its identifier. Allow about ten minutes if the key already exists locally. These commands change your GitHub account, but do not require sudo.

The route

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

This guide describes GitHub CLI 2.87.3, installed here from the gh package. The command's current 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.

1. Check authentication before changing the account

Run the status check first. It is read-only and helps prevent 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. Save the key ID from this output only when you have identified the key you intend to remove. Do not assume that a key's email address is 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, not 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. If you need 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. 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 above passes, upload the file and optionally supply 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 command's documented input is [<key-file>]; a dash can be used for standard input, which lets you avoid 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

Do not treat a success message as 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

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

5. Delete an obsolete key only after a second check

Deletion is irreversible from this command's point of view. It removes the selected key from the GitHub account, so do not use a guessed or truncated identifier. First list the keys, then copy the exact ID for 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 is suitable only when an automated process has already made the selection safely:

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

There is no undo flag in gh gpg-key delete. If you removed the wrong key, recover by exporting the same public key from a trusted local keyring or backup and adding it again. Verify its fingerprint before re-adding it. 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. For an add, the fingerprint should now appear in the account. For a delete, it should be absent:

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

A key being listed does not prove that every future commit will be marked as verified. Git must use the matching private key, the commit email must be associated with the GitHub account, and the signature must be valid. Those are separate signing configuration checks. This command group only manages the public key registration.

Done means

  • gh auth status names the intended GitHub account.
  • gh gpg-key list was checked before and after the account change.
  • The uploaded material was a public key, and its fingerprint matched the local copy.
  • Any deletion used an exact listed key ID and was confirmed deliberately.
  • The private key stayed in the local protected keyring and was never sent to GitHub.