Add a Public GPG Key to GitHub with gh

Registering a signing key with gh gpg-key add takes minutes once you know which key you actually mean to upload. The command uploads a public key file: it does not generate a key, upload your private key, or configure Git signing on its own.

Allow about ten minutes. You need an existing GPG key pair, the gh package, an authenticated GitHub CLI session and permission to change the target account. These examples use gh 2.87.3, installed here on 23 September 2026. No step needs sudo.

1. Check the installed command

Start with read-only checks. These confirm the version and the exact options available on this machine:

$ gh --version
$ gh gpg-key add --help
Add a GPG key to your GitHub account

USAGE
  gh gpg-key add [<key-file>] [flags]

FLAGS
  -t, --title string   Title for the new key

The file argument is optional in the synopsis, but naming it explicitly makes it obvious which public key you are uploading. The only command-specific option is --title, or -t. Do not confuse this with gh ssh-key add, which manages a different kind of credential.

$ gh auth status

Read the result carefully. If it reports no authenticated account, stop and run the normal gh auth login flow. Do not paste an access token into a command line or store one in shell history.

2. Identify the key without exposing its secret

List the secret keys available to GnuPG, with long identifiers shown:

$ gpg --list-secret-keys --keyid-format LONG

Pick the key you actually use for Git signing. You need its fingerprint or long key ID for inspection, not its private material. If this shows no suitable key, stop and create or import one through your established key-management process first.

A public key export is safe to share with GitHub, but the output path is still worth getting right. Use a temporary directory with restrictive permissions:

$ umask 077
$ install -d -m 700 "$HOME/tmp-gpg-upload"
$ gpg --armor --export KEY_ID > "$HOME/tmp-gpg-upload/github-signing-key.asc"
$ sed -n '1p' "$HOME/tmp-gpg-upload/github-signing-key.asc"
-----BEGIN PGP PUBLIC KEY BLOCK-----

Replace KEY_ID with the fingerprint or long ID you selected. The first line should read as an ASCII-armoured public key block.

This directory and file are local, throwaway state. Once the account change is verified, remove them with rm -- "$HOME/tmp-gpg-upload/github-signing-key.asc" and rmdir -- "$HOME/tmp-gpg-upload". That deletes only the exported copy, not your GPG key pair.

3. Review the key before changing the account

Ask GnuPG to show the public key details straight from the file. Another read-only checkpoint:

$ gpg --show-keys --with-fingerprint "$HOME/tmp-gpg-upload/github-signing-key.asc"

Check the fingerprint and identity against the key you meant to use. Fingerprints are the comparison that matters; a short key ID is not enough once you are untangling an identity mix-up. Wrong fingerprint means stop and export the correct key instead.

Do not upload an export made from an untrusted or unexpected key. Adding a key changes which commits GitHub will associate with your account, so this is a security-sensitive change even though the file itself holds no private key.

4. Add the public key with a clear title

Pick a title that identifies the machine or purpose without putting secrets in it, then run the state-changing command:

$ gh gpg-key add "$HOME/tmp-gpg-upload/github-signing-key.asc" \
    --title "workstation Git signing"

The title is only a label in your GitHub account. It changes nothing about the GPG key's user ID, expiration or trust settings. This is a remote account change, so check the account and title before pressing enter. Wrong host or account in gh auth status: fix that first.

Treat the exit status as the first signal, then confirm through the list command rather than assuming a returned prompt means the right key landed.

5. Verify the account entry

List the GPG keys registered to the authenticated GitHub account:

$ gh gpg-key list

Find the entry whose fingerprint matches the value from gpg --show-keys, and check its title too. A different fingerprint means you added, or are looking at, the wrong key or account. Do not start signing commits until this comparison checks out.

Registering a public key does not make Git use it. Signing still needs local configuration, the right signing key and signing format. Test that separately with your normal Git workflow, and never use the exported public file as a signing key.

6. Recover from a wrong upload

Deleting a key changes the account again, so do not automate it against a guessed ID. List the entries first and copy the exact key ID for the unwanted key:

$ gh gpg-key list
$ gh gpg-key delete KEY_ID

The delete command asks for confirmation unless you add --yes. Leave the prompt on while you are correcting a human mistake. If you remove the wrong key, there is no restore command: re-export its public key from a safe local key store, add it again, and verify the fingerprint. Do not delete the private key from GnuPG as a way to undo a GitHub registration.

Once the account entry checks out, clean up the temporary export:

$ rm -- "$HOME/tmp-gpg-upload/github-signing-key.asc"
$ rmdir -- "$HOME/tmp-gpg-upload"

If the upload failed, read the error before retrying. Check authentication, the file path and the key contents first: retrying blindly can create duplicate labels and muddy the audit trail.