Skip to main content

how to sign your commits with a GPG key so that "Verified" badge appears next to your name on GitHub?

· 5 min read
Serhii Hrekov
Serhii Hrekov
software engineer, creator, artist, programmer, projects founder

That "Verified" badge on GitHub isn't just for show—it’s a cryptographic guarantee that the code actually came from you and hasn't been tampered with. Without it, anyone can technically spoof your name and email in a Git commit.

By using GPG (GNU Privacy Guard), you "seal" your commits with a private key that only you possess. GitHub then uses your public key to verify that seal.

🔐 The "Verified" Workflow​

1. Install GPG​

First, ensure you have the GPG command-line tools installed.

  • macOS: brew install gpg2
  • Windows: Download Gpg4win
  • Linux: sudo apt install gnupg (usually pre-installed)

2. Generate Your Key Pair​

Run the following command and follow the prompts.

gpg --full-generate-key

Pro Tips for the Prompts:

  • Kind of key: Select (1) RSA and RSA (default).
  • Key size: Choose 4096 bits for maximum security.
  • Expiration: 0 (key does not expire) or your preferred timeframe.
  • Identity: Use the exact same email address linked to your GitHub account.

3. Retrieve Your Public Key​

You need to export your public key to give it to GitHub. First, find your Key ID:

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

Look for the line starting with sec. The ID is the string of characters after the slash (e.g., 3AA5C34371567BD2). Now, export it:

gpg --armor --export 3AA5C34371567BD2 
# Replace with YOUR ID

Copy everything from -----BEGIN PGP PUBLIC KEY BLOCK----- to -----END PGP PUBLIC KEY BLOCK-----.

4. Add the Key to GitHub​

  1. Go to GitHub Settings.
  2. Click SSH and GPG keys.
  3. Click New GPG key and paste your block.

5. Configure Git to Sign Locally​

Now tell your computer to use this key for every commit you make.

# Tell Git which key to use
git config --global user.signingkey 3AA5C34371567BD2

# Enable signing for ALL commits automatically
git config --global commit.gpgsign true

Windows/macOS Note: If you get an error like gpg: signing failed: Inappropriate ioctl for device, add export GPG_TTY=$(tty) to your .bashrc or .zshrc file.

🛠️ Testing the Badge​

Make a small change, commit it, and push:

git commit -m "Testing my new verified badge"
git push

If you check your commit history on GitHub now, you should see that beautiful green Verified button next to your name!

📚 Sources & Technical Refs​

📋 Troubleshooting Checklist​

IssueSolution
No "Verified" badge?Ensure the email in gpg matches your GitHub email exactly.
Asking for password every time?Use a GPG Agent (like Keychain on Mac) to cache the passphrase.
Commit fails?Check if gpg is in your system PATH using which gpg.
Windows "Inappropriate ioctl" error?Add export GPG_TTY=$(tty) to your shell config file.