#git #encryption

How to Set Up GPG Commit Signing for GitHub on Windows (With Troubleshooting)

Adding GPG signing to your Git commits gives them a Verified badge on GitHub, proving they came from you and haven’t been altered. On Windows, the setup can be a bit tricky — especially if you’ve got multiple GPG installs or run into permission issues.

This guide covers installation, configuration, verification, and common troubleshooting.

1. Install GPG

You need the gpg.exe program to generate keys and sign commits.
The easiest way on Windows is Gpg4win. Steps:

Download and run the installer.
Keep GnuPG checked (core component).
Optionally keep Kleopatra for GUI key management.
Install for all users (recommended) to avoid permission issues.

2. Generate a GPG Key

Open PowerShell or Git Bash and run:

gpg --full-generate-key

When prompted:

Key type: RSA and RSA
Key size: 4096
Expiration: 1y or 0 for never
Name and email: Use the same email as your GitHub account (verified there)
Passphrase: Optional but recommended

3. Get Your Key’s Fingerprint

List your secret keys:

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

Then get the full 40-character fingerprint:

gpg --fingerprint

Example:

pub   rsa4096 2025-08-08 [SC]
      1234ABCD5678EF901234ABCD5678EF901234ABCD
uid           [ultimate] Your Name <you@example.com>

4. Add Your GPG Key to GitHub

Export the public key:

gpg --armor --export <FULL_FINGERPRINT>

Copy the entire output (including BEGIN and END lines).

On GitHub:

Go to Settings → SSH and GPG keys → New GPG key
Direct link
Paste your key and save.

5. Configure Git to Use the Key

Tell Git where gpg.exe is and which key to use:

git config --global gpg.program "C:/Program Files (x86)/GnuPG/bin/gpg.exe"
git config --global user.signingkey <FULL_FINGERPRINT>

Enable auto-signing:

git config --global commit.gpgsign true

(Optional) Sign all tags too:

git config --global tag.gpgSign true

6. Test It

echo "test" | gpg --clearsign
git commit -m "Signed commit test"
git log --show-signature -1

You should see:

gpg: Good signature from "Your Name <you@example.com>"

Push to GitHub — the commit should have a Verified badge.

7. Troubleshooting & Common Problems

Commit shows “Unverified” on GitHub

The GPG key isn’t added to GitHub → add via step 4.
The commit email doesn’t match your GPG key’s UID →
Check with:

git config user.email
gpg --list-keys

Add the email to GitHub and verify it.

error: gpg failed to sign the data: no secret key

Git is pointing at a GPG install that doesn’t have your private key.
Check with:

git config --global gpg.program
gpg --list-secret-keys --keyid-format=long

If empty → generate or import your key into that GPG instance.

cannot spawn ...\bin: Permission denied

You pointed Git to the folder, not the gpg.exe file.
Fix:

git config --global gpg.program "C:/path/to/gpg.exe"

No passphrase prompt / `pinentry` errors

On Windows, you need a pinentry program (e.g., pinentry-qt.exe).
Add to:

C:\Users\<you>\AppData\Roaming\gnupg\gpg-agent.conf

pinentry-program "C:\Program Files (x86)\GnuPG\bin\pinentry-qt.exe"

Reload agent:

gpgconf --kill gpg-agent

Multiple GPG installs cause confusion

Git for Windows includes its own gpg.exe at:

C:/Program Files/Git/usr/bin/gpg.exe

Make sure Git points to the one that actually has your keys.

Keys in wrong location

GPG keys are stored in the “home directory” shown by:

gpg --version

Look for Home: C:/Users/<you>/AppData/Roaming/gnupg.
If you have multiple GPGs, each might use its own home directory.

Final Tips

Use the full fingerprint for user.signingkey — not the short key ID.
If you reinstall GPG, back up your keys:

gpg --armor --export-secret-keys <fingerprint> > private-key.asc

Signing tags is great for releases — GitHub will show “Verified” for the tag itself.

If you follow these steps, your commits and tags will be cryptographically authenticated, giving you and your collaborators peace of mind — and that sweet green Verified badge on GitHub.