GPG Git Setup Verification Guide

gpg-git-setup-verification.md

GPG Git Setup Verification Guide

A comprehensive checklist to verify your local GPG and Git signing configuration is working correctly.

Prerequisites

Before running these verification commands, ensure you have:

• GPG (GNU Privacy Guard) installed on your system
• Git installed and configured with your user information
• A GPG key pair generated (if not, see the "Generating a GPG Key" section below)

Verification Commands

1. Check GPG Installation and Version

gpg --version

Purpose: Verifies that GPG is installed and displays the version information.

Expected Output:

gpg (GnuPG) 2.x.x
libgcrypt x.x.x
...

What to check:

• GPG version should be 2.0 or higher for best compatibility with Git
• Command executes without errors

Troubleshooting:

• If command not found: Install GPG using your package manager
  • macOS: brew install gnupg
  • Ubuntu/Debian: sudo apt-get install gnupg
  • Windows: Download from gnupg.org

---

2. List Available GPG Secret Keys

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

Purpose: Displays all GPG secret (private) keys stored in your keyring with long key ID format.

Expected Output:

/Users/username/.gnupg/pubring.kbx
----------------------------------
sec   rsa4096/ABCD1234EFGH5678 2024-01-01 [SC]
      1234567890ABCDEF1234567890ABCDEF12345678
uid                 [ultimate] Your Name <your.email@example.com>
ssb   rsa4096/IJKL9012MNOP3456 2024-01-01 [E]

Key Components Explained:

• sec: Secret (private) key
• rsa4096: Key type and length (RSA with 4096 bits)
• ABCD1234EFGH5678: The key ID (this is what you'll use for Git configuration)
• [SC]: Key capabilities (S=Signing, C=Certification)
• uid: User ID associated with the key
• ssb: Secret subkey
• [E]: Encryption capability

What to check:

• At least one secret key should be listed
• The email address should match your Git commit email
• Key should not be expired or revoked

Troubleshooting:

• If no keys are listed: You need to generate a GPG key (see section below)
• If wrong email: Generate a new key or add a new UID to existing key

---

3. Verify Git Signing Key Configuration

git config --global --get user.signingkey

Purpose: Shows which GPG key ID Git is configured to use for signing commits.

Expected Output:

ABCD1234EFGH5678

What to check:

• The output should match one of the key IDs from step 2
• Should not be empty

If not configured:

git config --global user.signingkey ABCD1234EFGH5678

Replace ABCD1234EFGH5678 with your actual key ID from step 2.

---

4. Check Automatic Commit Signing

git config --global --get commit.gpgsign

Purpose: Verifies if Git is configured to automatically sign all commits.

Expected Output:

true

What to check:

• Output should be true for automatic signing
• Empty output means automatic signing is disabled

To enable automatic signing:

git config --global commit.gpgsign true

Note: You can also sign commits individually using git commit -S without global configuration.

---

5. Verify GPG Program Path

git config --global --get gpg.program

Purpose: Shows the path to the GPG executable that Git uses for signing.

Expected Output:

• May be empty (Git uses default gpg in PATH)
• Or a specific path like /usr/local/bin/gpg or /opt/homebrew/bin/gpg

What to check:

• If empty, Git will use the default GPG found in your system PATH
• If specified, verify the path exists and is correct

Common scenarios requiring explicit configuration:

• Multiple GPG versions installed
• GPG installed in non-standard location
• macOS with Homebrew (may need explicit path)

To set explicit path (if needed):

# macOS Homebrew example
git config --global gpg.program /opt/homebrew/bin/gpg

# Linux example
git config --global gpg.program /usr/bin/gpg

# Windows example
git config --global gpg.program "C:/Program Files (x86)/GnuPG/bin/gpg.exe"

---

6. Test GPG Signing Capability

echo "test" | gpg --clearsign

Purpose: Tests if GPG can actually sign data using your default key. This is a functional test of the signing process.

Expected Output:

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

test
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCAAdFiEE...
...
-----END PGP SIGNATURE-----

What to check:

• Should display a PGP signed message block
• May prompt for your GPG key passphrase (if set)
• Should complete without errors

Troubleshooting:

• "No secret key": No default key configured, specify with gpg --default-key KEYID --clearsign
• Passphrase prompt doesn't appear: GPG agent might not be running (see next step)
• "Inappropriate ioctl for device": GPG_TTY not set correctly

  export GPG_TTY=$(tty)
  echo "export GPG_TTY=\$(tty)" >> ~/.zshrc # or ~/.bashrc

---

7. Verify GPG Agent Status

gpg-connect-agent /bye

Purpose: Checks if the GPG agent (responsible for managing key passphrases and caching) is running and responsive.

Expected Output:

OK

What to check:

• Should return "OK" quickly
• No error messages

Troubleshooting:

• Agent not running: Rtart it with gpgconf --launch gpg-agent
• Connection issues: Check GPG agent socket

  # Check agent info
  echo $GPG_AGENT_INFO
  
  # Restart agent
  gpgconf --kill gpg-agent
  gpgconf --launch gpg-agent

Common GPG agent configuration (~/.gnupg/gpg-agent.conf):

# Cache passphrase for 8 hours
default-cache-ttl 28800
max-cache-ttl 28800

# Use pinentry for GUI passphrase prompt (macOS example)
pinentry-program /opt/homebrew/bin/pinentry-mac

Additional Useful Agent Commands

check agent status

$ gpg-connect-agent "GETINFO version" /bye
D 2.4.0
OK

list cached keys

$ gpg-connect-agent "KEYINFO --list" /bye
S KEYINFO 3AR5C34371567CD2 D - - - P - - -
OK

clear passphrase cache

$ gpg-connect-agent reloadagent /bye
OK

update agent configuration

$ gpg-connect-agent "RELOADAGENT" /bye
OK

---

Complete Verification Script

Run all checks in sequence:

#!/bin/bash

echo "=== GPG Version Check ==="
gpg --version

echo -e "\n=== GPG Secret Keys ==="
gpg --list-secret-keys --keyid-format LONG

echo -e "\n=== Git Signing Configuration ==="
echo "Signing key: $(git config --global --get user.signingkey)"
echo "Auto-sign commits: $(git config --global --get commit.gpgsign)"
echo "GPG program: $(git config --global --get gpg.program)"

echo -e "\n=== GPG Signing Test ==="
echo "test" | gpg --clearsign

echo -e "\n=== GPG Agent Status ==="
gpg-connect-agent /bye

---

Generating a GPG Key (If Needed)

If you don't have a GPG key yet:

# Generate a new key
gpg --full-generate-key

# Follow the prompts:
# 1. Select key type (recommend: RSA and RSA)
# 2. Key size (recommend: 4096 bits)
# 3. Expiration (recommend: 1 year or more)
# 4. Enter your name and email (use your Git commit email)
# 5. Set a strong passphrase

After generation:

# List keys to get the key ID
gpg --list-secret-keys --keyid-format LONG

# Configure Git to use your new key
git config --global user.signingkey YOUR_KEY_ID
git config --global commit.gpgsign true

see also Generating a new GPG key

---

Testing Your Setup with a Real Commit

Create a test repository to verify everything works:

# Create test repo
mkdir gpg-test && cd gpg-test
git init

# Create and commit a test file
echo "GPG test" > test.txt
git add test.txt
git commit -S -m "Test signed commit"

# Verify the signature
git log --show-signature -1

Expected output should include:

gpg: Signature made ...
gpg: Good signature from "Your Name <your.email@example.com>"

---

Platform-Specific Notes

macOS

• May need to set GPG_TTY in your shell profile
• Homebrew GPG might require explicit path configuration
• Consider installing pinentry-mac for better passphrase prompts

Windows

• Use Git Bash or WSL for best compatibility
• May need to configure GPG path explicitly
• Ensure GPG is in your system PATH

Linux

• Usually works out of the box
• Check SELinux/AppArmor if signature verification fails
• Ensure proper permissions on ~/.gnupg directory (700)

---

Common Issues and Solutions

Issue: "gpg failed to sign the data"

Solutions:

1. Check GPG_TTY is set: export GPG_TTY=$(tty)
2. Verify key hasn't expired: gpg --list-keys
3. Test signing manually: echo "test" | gpg --clearsign
4. Restart GPG agent: gpgconf --kill gpg-agent

Issue: "No secret key" when committing

Solutions:

1. Verify key ID: gpg --list-secret-keys --keyid-format LONG
2. Check Git configuration: git config --global user.signingkey
3. Ensure email matches between Git and GPG

Issue: "Inappropriate ioctl for device"

Solution: Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export GPG_TTY=$(tty)

---

Additional Resources

• Git GPG Signing Documentation
• GitHub GPG Key Guide
• GnuPG Documentation

---

Security Best Practices

1. Use strong passphrases: Protect your private key with a robust passphrase
2. Set key expiration: Keys should expire and be renewed periodically (annually recommended)
3. Backup your keys: Store encrypted backups securely
4. Revocation certificate: Generate and store safely in case key is compromised
5. Verify signatures: Always check signatures on important repositories
6. Upload public key: Share your public key on GitHub/GitLab for signature verification

# Export public key for uploading to GitHub/GitLab
gpg --armor --export YOUR_KEY_ID