How to Sign Your Git Commits with a GPG Key

Generate or use an existing GPG key by installing GPG and running gpg --full-generate-key with RSA 4096-bit key size, matching your Git email, and setting a secure passphrase. 2. Find your GPG key ID using gpg --list-secret-keys --keyid-format LONG and extract the key ID (e.g., ABC1234567890DEF) from the sec line. 3. Configure Git to use the key by setting git config --global user.signingkey ABC1234567890DEF and ensuring git config --global user.email matches the GPG email, then optionally enable global signing with git config --global commit.gpgsign true or use git commit -S per commit. 4. Add your GPG public key to GitHub/GitLab by exporting it with gpg --armor --export ABC1234567890DEF and pasting the full block into the platform's GPG key settings. 5. Resolve common issues by verifying email and key ID match, ensuring GPG is in PATH, setting git config --global gpg.program appropriately for your OS, and exporting GPG_TTY=$(tty) in your shell profile to fix pinentry hangs. Optionally sign tags with git tag -s and verify with git tag -v, ensuring all systems use consistent emails and keys for verified, trusted commits.

Signing your Git commits with a GPG key adds a layer of authenticity and trust, proving that you are the true author of the changes. This is especially useful in team environments or open-source projects where verifying contributor identities matters. Here’s how to set it up step by step.

1. Generate or Use an Existing GPG Key

If you don’t already have a GPG key, you’ll need to generate one.

Install GPG if it’s not already installed:

# On macOS
brew install gnupg

# On Ubuntu/Debian
sudo apt-get install gnupg

# On Windows (via Git Bash or WSL)
# GPG usually comes with Git for Windows

Now generate a new GPG key:

gpg --full-generate-key

You’ll be prompted to:

• Choose key type (select RSA and RSA)
• Key size (use 4096)
• Expiration period (optional)
• Your name and email (must match your Git config!)
• A passphrase (keep it secure)

Alternatively, use this command for a non-interactive version:

gpg --batch --generate-key <<EOF
Key-Type: RSA
Key-Length: 4096
Subkey-Type: RSA
Name-Real: Your Name
Name-Email: your.email@example.com
Expire-Date: 0
Passphrase: your-passphrase
%commit
EOF

2. Find Your GPG Key ID

List your secret keys to get the key ID:

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

Look for a line like:

sec   rsa4096/ABC1234567890DEF 2024-01-01 [SC]

Here, ABC1234567890DEF is your GPG key ID.

You can also extract just the key ID with:

gpg --list-secret-keys --keyid-format LONG your.email@example.com | grep ^sec | awk '{print $2}' | cut -d'/' -f2

3. Tell Git to Use Your GPG Key

Set the GPG key in your Git config:

git config --global user.signingkey ABC1234567890DEF

Also ensure your user email in Git matches the one used in the GPG key:

git config --global user.email "your.email@example.com"

Enable commit signing globally (optional):

git config --global commit.gpgsign true

Or sign individual commits by adding -S:

git commit -S -m "This commit is signed"

? If you don’t want to sign every commit globally, skip enabling commit.gpgsign and just use -S when needed.

4. Add GPG Public Key to GitHub/GitLab/Other Platforms

To get the verified badge on GitHub, you need to add your public key.

Export your public key:

gpg --armor --export ABC1234567890DEF

This outputs something like:

-----BEGIN PGP PUBLIC KEY BLOCK-----
...
-----END PGP PUBLIC KEY BLOCK-----

Copy the entire block (including BEGIN and END lines), then:

• GitHub: Go to Settings → SSH and GPG keys → New GPG key → Paste
• GitLab: Settings → GPG Keys → Paste
• Bitbucket: Similar process under account settings

Once added, your commits will show as "Verified" when pushed.

5. Fix Common Issues

? GPG "No Secret Key" Error

Even if you have the key, Git might not find it. Make sure:

• The email in Git matches the GPG key exactly
• You're using the correct key ID
• Your GPG binary is in PATH

On macOS, you may need to set:

git config --global gpg.program gpg

? Linux: GPG Pinentry Issues

If signing hangs, it might be due to missing pinentry. Install it:

sudo apt install pinentry-gtk2  # or pinentry-tty

Set the GPG agent to use the right TTY:

export GPG_TTY=$(tty)

Add that to your shell profile (.zshrc, .bashrc) to avoid future issues.

? Windows: Using Git Bash

Make sure you’re using the GPG version bundled with Git:

git config --global gpg.program "C:\Program Files\Git\usr\bin\gpg.exe"

And set:

export GPG_TTY=$(tty)

in your .bashrc.

Bonus: Sign Tags

GPG-signed tags are also useful:

git tag -s v1.0.0 -m "Signed release"

Verify with:

git tag -v v1.0.0

That’s it. With GPG signing enabled, your commits are cryptographically verified. It’s a small step for security, but a big one for trust in collaborative development. Just make sure your key is backed up and your email matches across systems.

Basically: generate key → set in Git → add public key to platform → sign commits. Not complex, but easy to miss a detail.

The above is the detailed content of How to Sign Your Git Commits with a GPG Key. For more information, please follow other related articles on the PHP Chinese website!