Generate, configure GPG Keys for github

GPG.md

GitHub GPG Key Setup Manual

---

This guide shows how to generate a GPG key, configure Git to use it, and add it to GitHub so your commits can be verified.

Prerequisites

• A GitHub account with a verified email address.
• Git installed on your computer.
• GPG installed on your computer.

GitHub recommends verifying your email before generating a key, because the email in your GPG key must match the identity you use for Git commits [web:4][web:1].

1. Install GPG

macOS

brew install gnupg

Ubuntu / Debian

sudo apt update
sudo apt install gnupg

Windows

Install Gpg4win from the official website.

2. Generate a GPG key

Open Terminal or Git Bash and run:

gpg --full-generate-key

GitHub’s documentation also supports gpg --generate-key for newer GPG versions, but --full-generate-key gives you more control over the options [web:2][web:4].

When prompted:

• Choose RSA and RSA if available.
• Use a key size of 4096.
• Set an expiration date if desired.
• Enter your full name.
• Enter the email address linked to your GitHub account.
• Create a strong passphrase.

3. List your keys

After creating the key, list your secret keys:

gpg --list-secret-keys --keyid-format=long

Look for the key ID after sec. You will need it for Git configuration [web:1].

4. Export the public key

Copy your public key in ASCII format:

gpg --armor --export YOUR_KEY_ID

Replace YOUR_KEY_ID with the long key ID from the previous step. GitHub asks you to copy the block beginning with -----BEGIN PGP PUBLIC KEY BLOCK----- and ending with -----END PGP PUBLIC KEY BLOCK----- [web:4][web:7].

5. Add the key to GitHub

1. Go to GitHub and open Settings.
2. In the sidebar, select SSH and GPG keys.
3. Under GPG keys, click New GPG key.
4. Add a title for the key.
5. Paste the public key.
6. Click Add GPG key.
7. Complete any authentication prompt if shown [web:7].

6. Configure Git to use the key

Tell Git which key to use for signing:

git config --global user.signingkey YOUR_KEY_ID

If you want Git to sign every commit automatically:

git config --global commit.gpgsign true

GitHub documents this global signing setting for automatic commit signing [web:1][web:3].

7. Test commit signing

Create or amend a commit, then verify that Git signs it:

git commit -S -m "My signed commit"

If global signing is enabled, you can also use a normal commit command:

git commit -m "My signed commit"

GitHub should show the commit as verified after the key is correctly added and the commit email matches your GitHub email [web:1][web:6].

8. Troubleshooting

• Make sure the email in the key matches your GitHub account email.
• Make sure Git is using the same key you added to GitHub.
• If your commit is not verified, confirm commit.gpgsign is enabled or use -S.
• If GitHub does not show the key, paste the full public key block again.

Useful commands

gpg --list-secret-keys --keyid-format=long
gpg --armor --export YOUR_KEY_ID
git config --global user.signingkey YOUR_KEY_ID
git config --global commit.gpgsign true
git commit -S -m "Signed commit"

9. Where GPG stores your keys

By default, GPG stores its configuration, public keyring, and private keys in:

~/.gnupg

On some systems, this location can be changed with:

• GNUPGHOME
• gpg --homedir /path/to/dir

Secret keys are stored in the GnuPG private key area inside that home directory [web:26][web:28][web:30].

Useful locations

• Public keys and keyring files: ~/.gnupg
• Secret key material: ~/.gnupg/private-keys-v1.d
• Configuration files: ~/.gnupg/gpg.conf and related files [web:28][web:30].

10. List your keys

Show all public keys:

gpg --list-keys

Show all secret keys:

gpg --list-secret-keys --keyid-format=long

Use these commands whenever you need to confirm which keys exist on your machine [web:27][web:30].

11. Delete a local GPG key

Delete the secret key first

gpg --delete-secret-key YOUR_KEY_ID

Then delete the public key

gpg --delete-key YOUR_KEY_ID

GnuPG expects the secret key to be removed first if it still exists, and will prompt you accordingly [web:27][web:21].

12. Remove a GPG key from GitHub

To remove a key from your GitHub account, go to:

• GitHub Settings
• SSH and GPG keys
• GPG keys
• Remove the key you no longer want

You can also use the GitHub CLI:

gh gpg-key delete <key-id>

Deleting the key from GitHub affects verification on GitHub, while deleting it locally removes it from your computer [web:23][web:31].

13. Optional safety step

Before (deleting a key)[https://www.gnupg.org/gph/en/manual/r1045.html], consider revoking it if it may have been compromised. Revocation is safer than simple deletion because it tells others the key should no longer be trusted.

14. Revoke a GPG key

If your key is compromised, lost, or no longer needed, revoke it instead of only deleting it.

1) Generate a revocation certificate

gpg --output revoke.asc --gen-revoke YOUR_KEY_ID

Save this file somewhere secure. Anyone with this certificate can revoke your key, so do not store it in an unsafe place [web:15][web:47].

2) Import the revocation certificate

gpg --import revoke.asc

This marks the key as revoked in your local keyring [web:17][web:39].

3) Export the revoked public key

gpg --armor --export YOUR_KEY_ID > revoked-public-key.asc

4) Remove the old key from GitHub

Delete the old GPG key from GitHub Settings → SSH and GPG keys → GPG keys. GitHub community guidance notes that some users then re-add the revoked public key so GitHub can display the revoked or expired state consistently [web:34][web:17].

5) Create a new key

Generate a new GPG key and update Git to use it for future signed commits.