Add a Public GPG Key to GitHub with gh

You will finish with the public half of an existing GPG key registered on your GitHub account, using the installed GitHub CLI command gh gpg-key add. 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. This confirms 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 using an explicit file makes it clear which public key is being uploaded. The only command-specific option is --title, or -t. Do not confuse this command with gh ssh-key add, which manages a different kind of credential.

Checkpoint: confirm that the CLI is authenticated before preparing the upload:

$ gh auth status

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

2. Identify the key without exposing its secret

List the secret keys available to GnuPG, showing long identifiers:

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

Choose the key that you actually use for Git signing. You need its fingerprint or long key ID for inspection, but you do not need to export the private material. If this command shows no suitable key, stop and create or import one through your established key-management process before continuing.

A public key export is safe to share with GitHub, but it is still worth checking the output path and contents. Use a temporary file in a 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 identify an ASCII-armoured public key block. If the file starts with private-key material, or if the export command reports an error, do not upload it. Delete the file and investigate the key selection.

This directory and file are local state. After the account change is verified, remove them with rm -- "$HOME/tmp-gpg-upload/github-signing-key.asc" and rmdir -- "$HOME/tmp-gpg-upload". That removes 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 from the file. This is another read-only checkpoint:

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

Check the displayed fingerprint and user identity against the key you intended to use. Fingerprints are the useful comparison value; a short key ID is not enough when you are resolving an identity mistake. If the fingerprint is wrong, stop and export the correct key instead.

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

4. Add the public key with a clear title

Choose 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 for the key in your GitHub account. It does not alter the GPG key's user ID, expiration or trust settings. This command changes remote account state, so review the account and title before pressing Enter. If your GitHub CLI session targets a different host or account than expected, stop and correct that authentication context first.

Treat the command's exit status as the first signal, then verify through the list command rather than assuming that a returned shell prompt means the expected key was added.

5. Verify the account entry

List the GPG keys registered with the authenticated GitHub account:

$ gh gpg-key list

Find the entry whose fingerprint matches the value from gpg --show-keys. Check its title as well. A different fingerprint means you added, or are viewing, the wrong key or account. Do not begin signing commits until this comparison is correct.

Remember the boundary: registering a public key does not make Git use it. Git signing still needs local configuration such as the correct 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 with a guessed ID. First list the entries 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 enabled while 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 and add it again, then verify the fingerprint. Do not delete the private key from GnuPG as a way to undo a GitHub registration.

Once the account entry is verified, clean up the temporary public export:

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

If the upload failed, inspect the error before retrying. Check authentication, the file path and the public-key contents first. Retrying blindly can create duplicate labels and makes the audit trail harder to read.