A complete, beginner-friendly guide to signing Git commits with GPG keys and earning the verified badge on GitHub. Includes step-by-step instructions for Windows, macOS, and Linux, plus troubleshooting and security best practices.
Loading readme…
The complete, beginner-friendly guide to signing your Git commits with GPG keys and earning that verified badge on GitHub!
Run these commands in order:
# 1) Generate your key (full wizard)
gpg --full-generate-key
# 2) Find your key ID (copy the part after the /)
gpg --list-secret-keys --keyid-format=long
# 3) Configure Git to use your key
git config --global user.signingkey YOUR_KEY_ID
# 4) (Optional) Always sign commits and tags
git config --global commit.gpgsign true
git config --global tag.gpgsign true
# 5) Export your public key (copy entire block)
gpg --armor --export YOUR_KEY_ID
Then add the exported public key in GitHub → Settings → "SSH and GPG keys" → "New GPG key".
Make a quick test:
git commit -m "Test GPG signing"
git push origin main
You should see the "Verified" badge on GitHub. 🎉
Copy/paste to cache your GPG passphrase for the session:
mkdir -p ~/.gnupg \
&& printf "default-cache-ttl 86400\nmax-cache-ttl 604800\n" >> ~/.gnupg/gpg-agent.conf \
&& gpgconf --reload gpg-agent
Note: macOS users can also install GUI pinentry (brew install pinentry-mac) and configure it via GPG Tools.
If you don't want to enter your passphrase on every signed commit, enable GPG agent caching. You'll enter it once per session, then it auto-caches.
Linux/macOS:
# Create or edit the agent config
echo "default-cache-ttl 86400" >> ~/.gnupg/gpg-agent.conf
echo "max-cache-ttl 604800" >> ~/.gnupg/gpg-agent.conf
# Reload the agent
gpgconf --reload gpg-agent
macOS users may prefer GUI pinentry: brew install pinentry-mac and set it via GPG Tools.
Windows:
Create or edit %APPDATA%\gnupg\gpg-agent.conf with:
default-cache-ttl 86400
max-cache-ttl 604800
Restart Kleopatra (Gpg4win) or log out/in to reload the agent.
Security note: Longer cache TTLs improve convenience but reduce security if others can access your machine.
A comprehensive, beginner-friendly guide to generating GPG keys, configuring Git, and adding verified badges to your GitHub commits.
GPG (GNU Privacy Guard) commit signing is a security feature that cryptographically signs your Git commits using your private key. This proves that commits were actually made by you and haven't been tampered with.
When enabled, your commits display a "Verified" badge on GitHub, GitLab, and other platforms, showing that the commit is authentic.
Before starting, ensure you have:
To verify GPG is installed:
gpg --version
Open your terminal/command prompt and run:
gpg --full-generate-key
This opens the full key generation wizard with all customization options.
You'll be prompted to answer several questions:
Select RSA and RSA (default, option 1)
John Doe)The key generation will take a few moments (it's using random data). Once complete, you'll see your key details.
List all your GPG keys:
gpg --list-secret-keys --keyid-format=long
Output will look like:
sec rsa4096/ABC123DEF456GHI 2025-12-21 [SC]
1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ1234
uid [ultimate] John Doe <john@example.com>
Copy the key ID (the part after the /): ABC123DEF456GHI
Tell Git to use your GPG key for signing:
# Set your signing key globally
git config --global user.signingkey ABC123DEF456GHI
Replace ABC123DEF456GHI with your actual key ID from Step 2.
To automatically sign all commits:
git config --global commit.gpgsign true
To automatically sign all tags:
git config --global tag.gpgsign true
If you don't enable this globally, you can sign individual commits with:
git commit -S -m "Your message"
Get your public key to add to GitHub:
gpg --armor --export ABC123DEF456GHI
Replace ABC123DEF456GHI with your key ID.
This will output a block of text starting with -----BEGIN PGP PUBLIC KEY BLOCK----- and ending with -----END PGP PUBLIC KEY BLOCK-----. Copy the entire block (including the begin/end lines).
Make a test commit to verify GPG signing works:
# Make a small change to any file
git add .
git commit -m "Test GPG signing"
# You'll be prompted to enter your GPG passphrase
Push it:
git push origin main
Go to your GitHub repository. Your new commit should now show a "Verified" badge next to it!
If you have existing unsigned commits that you want to sign retroactively, use interactive rebase.
To sign the last 2 commits (adjust the number as needed):
git rebase -i HEAD~2
This opens an editor showing your commits:
pick ea25d62 First commit message
pick f65cd7b Second commit message
Change pick to edit for each commit you want to sign:
edit ea25d62 First commit message
edit f65cd7b Second commit message
Save and close the editor.
Git will stop at each commit. For each one:
# Sign the current commit
git commit --amend -S --no-edit
# Continue to the next commit
git rebase --continue
Repeat until all commits are signed. You'll be prompted for your GPG passphrase each time.
After rebasing, force-push the signed commits:
git push --force-with-lease origin main
The verified badges should now appear on all signed commits on GitHub!
Warning: This rewrites commit history. Only do this if:
Possible causes:
Solutions:
# Check your configured signing key
git config --global user.signingkey
# Verify the key exists
gpg --list-secret-keys --keyid-format=long
# Restart GPG agent (Linux/Mac)
gpgconf --kill gpg-agent
gpgconf --launch gpg-agent
# Windows: Restart Gpg4win or your system
# Verify your key was created
gpg --list-secret-keys
# Check for typos in your key ID
git config --global user.signingkey
This is normal! GPG caches passphrases for security. To adjust caching:
Linux/Mac - Edit ~/.gnupg/gpg-agent.conf:
default-cache-ttl 34560000
max-cache-ttl 34560000
Then reload:
gpgconf --reload gpg-agent
Windows - Configure via Kleopatra (Gpg4win) → Settings → GnuPG System
commit.gpgsign is enabled: git config --global commit.gpgsign trueYour key may have been deleted or the ID is wrong:
# List available keys
gpg --list-secret-keys --keyid-format=long
# Reconfigure with correct key ID
git config --global user.signingkey YOUR_CORRECT_KEY_ID
On some systems, GPG uses a GUI pinentry program:
# Check current pinentry
echo "GETINFO version" | gpg-connect-agent
# Force terminal pinentry (Linux/Mac)
echo "pinentry-program /usr/bin/pinentry-tty" >> ~/.gnupg/gpg-agent.conf
gpgconf --reload gpg-agent
# Find where GPG is installed
where gpg
# Configure Git to use the correct path (adjust path as needed)
git config --global gpg.program "C:\Program Files\Git\usr\bin\gpg.exe"
C:\Program Files\Git\usr\bin\gpg.exe, C:\Program Files (x86)\GnuPG\bin\gpg.exebrew install gnupg or use GPG Toolsgpg.program:
# Find where GPG is installed
which gpg
# Configure Git to use the correct path (adjust as needed)
git config --global gpg.program "/opt/homebrew/bin/gpg" # Apple Silicon (Homebrew)
git config --global gpg.program "/usr/local/bin/gpg" # Intel (Homebrew)
pinentry-curses or pinentry-tty)~/.gnupg has correct permissions (700)gpg.program if needed:
# Find GPG
which gpg
# Configure Git to use the correct path
git config --global gpg.program "/usr/bin/gpg"
gpgconf --reload gpg-agent# Check GPG installation
gpg --version
# Discover GPG path
# Windows:
where gpg
# macOS/Linux:
which gpg
# Configure Git to use a specific GPG program
# Windows (example):
git config --global gpg.program "C:\\Program Files\\Git\\usr\\bin\\gpg.exe"
# macOS (Homebrew):
git config --global gpg.program "/opt/homebrew/bin/gpg"
git config --global gpg.program "/usr/local/bin/gpg"
# Linux:
git config --global gpg.program "/usr/bin/gpg"
# Set your signing key globally
git config --global user.signingkey YOUR_KEY_ID
# Enable automatic signing for commits and tags
git config --global commit.gpgsign true
git config --global tag.gpgsign true
# List your secret (private) keys
gpg --list-secret-keys
# List your public keys
gpg --list-keys
# Export your public key
gpg --armor --export YOUR_KEY_ID
# Sign a single commit
git commit -S -m "Your message"
# Create a signed tag and verify it
git tag -s v1.0 -m "Release v1.0"
git tag -v v1.0
# Verify current commits are signed
git log --show-signature
# Sign the most recent commit
git commit --amend -S --no-edit
# Sign the last N commits using interactive rebase
git rebase -i HEAD~N
# (Change 'pick' to 'edit' for each commit, then run:)
git commit --amend -S --no-edit
git rebase --continue
# (Repeat for each commit)
# Force-push signed commits to remote
git push --force-with-lease origin main
# Reload GPG agent (Linux/macOS)
gpgconf --reload gpg-agent
gpg --export-secret-keys --armor YOUR_KEY_ID > my-private-key.asc
A: No! One GPG key can sign commits across all repositories and platforms (GitHub, GitLab, etc.).
A: You cannot recover it. You'll need to create a new GPG key and reconfigure Git.
A: Yes! Export your private key and import it on other machines:
# On original machine
gpg --export-secret-keys --armor YOUR_KEY_ID > my-key.asc
# On new machine
gpg --import my-key.asc
git config --global user.signingkey YOUR_KEY_ID
A: Minimal impact. GPG caches your passphrase, so you only enter it once per session.
A: Yes! GitLab, Bitbucket, and most platforms support verified commits. The setup process is similar.
A: Commits signed before expiration remain valid. Generate a new key and update Git/GitHub, or extend your key's expiration:
gpg --edit-key YOUR_KEY_ID
# Type: expire
# Set new expiration
# Type: save
A: Yes! As long as Git is configured for signing, any tool using Git will automatically sign commits.
A: No, but it's highly recommended for security and professionalism, especially in open-source projects.
Current version: v1.0 (2025-12-21)
See CHANGELOG.md for dated major/minor releases and notes on structural updates.
Found an issue or have a suggestion? Contributions are welcome!
git checkout -b feature/improvementgit push origin feature/improvementFor detailed contribution guidelines, including commit message conventions, see CONTRIBUTING.md.
Helpful contributions:
This guide is released under the MIT License - see the LICENSE file for details.
Done! Your commits will now be verified. 🎉
⭐ If this guide helped you, consider giving it a star and sharing it with others!
Made with ❤️ for the open-source community