You’ve generated a GPG key and configured Git. However how do you know it actually works together? This playbook provides a verification checklist. Each command isolates a specific component, making troubleshooting straightforward if something breaks:

# 1. Check GPG installation
gpg --version

# 2. Verify you have a key
gpg --list-secret-keys --keyid-format LONG

# 3. Check Git configuration
git config --global --get user.signingkey
git config --global --get commit.gpgsign
git config --global --get gpg.program

# 4. Test signing capability
echo "test" | gpg --clearsign

# 5. Verify agent is running
gpg-connect-agent /bye

Why does this matter?

It verifies you being the author of your commits. That proves the commit came from you (authenticity) and hasn’t been altered (integrity). It also establishes trust in open-source projects by preventing spoofing and forgery as well as providing a reliable audit trail for governance and compliance.

Preconditions

• GPG (GNU Privacy Guard) 2.2 or higher installed on your system installed on your system (check with gpg --version)
• Git installed and configured with your user information
• A GPG key pair generated (if not, see the “Generating a GPG Key” section below)

Commands explained

gpg --version

This command displays information about your GPG (GNU Privacy Guard) installation. Git signing works best with GPG 2.0+.

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

The --list-secret-keys flag of the command above lists your private gpg keys (the keys only you have). These are used for signing and decrypting. The --keyid-format LONG flag displays the keys in long format (16 hexadecimal characters). The long format is what Git typically need.

Example output

/home/user/.gnupg/pubring.kbx
------------------------------------
sec   rsa4096/3AR5C34371567CD2 2024-01-15 [SC] [expires: 2027-01-15]
      1234567890ABCDEF1234567890ABCDEF12345678
uid                 [ultimate] {your name} <{your email}>
ssb   rsa4096/B5086E5E8F4E3D1A 2024-01-15 [E] [expires: 2027-01-15]

Understanding the Output

/home/user/.gnupg/pubring.kbx

• Location of your GPG keyring file

sec rsa4096//3AR5C34371567CD2

• sec = secret (private) key
• rsa4096 = Key type and size (RSA algorithm, 4096 bits)
• /3AR5C34371567CD2 = Key ID in long format <- This is what you need for Git

2024-01-15 [SC] [expires: 2026-01-15]

• Creation date
• [SC] = Capabilities: Signing and Certification
• Expiration date (important for security)

1234567890ABCDEF...

• Full 40-character fingerprint (complete key identifier)

uid [ultimate]

• User ID = Your name and email associated with this key
• [ultimate] = Trust level (you fully trust your own key)

ssb rsa4096/B5086E5E8F4E3D1A

[E] = Encryption capability

ssb = secret subkey (used for specific operations)

git config –global –get user.signingkey

It shows which GPG key ID Git will use to sign your commits.

Example output

3AR5C34371567CD2

Git is configured to use the key with ID 3AR5C34371567CD2 for signing. This ID should match one from gpg --list-secret-keys output above. This is required for git gpg signing to work.

git config –global –get commit.gpgsign

Get the value of the commit.gpgsign setting from your global Git configuration. This setting shows whether Git should automatically sign commits with GPG. Possible values:

• true Every commit is automatically signed, that equivalent to always using git commit -S
• false or empty. Commits are NOT signed by default. Signing would need git commit -S command

git config –global –get gpg.program

This command checks which GPG executable Git will use for signing.

• Empty result = Git uses whatever gpg it finds in PATH (usually fine)
• Path result = Git uses that specific GPG binary (needed when you have multiple GPG versions or non-standard installations)

echo “test” | gpg –clearsign

This command tests if GPG can actually sign data using your private key. It’s a functional test that simulates what happens when Git tries to sign a commit.

gpg-connect-agent /bye

This is a health check for the GPG agent. It connects to the agent, sends the /bye command, and immediately closes the connection right after. It allows to check if the agent processes the command and what the answer is.

• OK – the agent works
• other output indicates agent issues

Getting Started with GPG Commit Signing

Now that you’ve verified your GPG and Git setup is working correctly, you’re ready to start signing your commits. This verification playbook ensures your local environment is properly configured before you begin contributing to projects that require signed commits.

Next Steps

1. Sign your first commit
   Test the setup in a new repository:
   git commit --allow-empty -S -m "Test signed commit"
git log --show-signature -1
   
2. Upload your public key
   Add your GPG public key to GitHub/GitLab so others can verify your signatures:
   bash gpg --armor --export YOUR_KEY_ID
   
3. Automate future commits
   Set commit.gpgsign to true, every commit is automatically signed
   
4. Troubleshooting Resources
   If any command failed, revisit the related sections above. You may also check:
   
   – https://gnupg.org/documentation/
   – https://git-scm.com/
   
5. Secure your keys
   – Use strong passphrase for your private key
   – Store backup securely (encrypted external drive)
   – Generate a revocation certificate: gpg --gen-revoke YOUR_KEY_ID
   – Consider using a hardware security key (YubiKey) for production use
   

You may also refer to https://gist.github.com/lotharschulz/4542ee8dbfe9cfd40076b31ef9c0e9a3.