I signed my commits with GPG for years before I actually understood what I was doing. Turns out, most of the guides out there make this way harder than it needs to be. Here are the five rules that actually matter.

GPG signing terminal
Your terminal after setting up GPG signing. Satisfying, isn't it.

1. Generate a GPG key ( not a weak one )

Start here. No key, no signing.

gpg --full-generate-key

Pick RSA and 4096 bits. Not 2048. Not "default". 4096. Set it to expire ( I use 2 years ), and pick a passphrase you can actually remember. Write it down somewhere. A real piece of paper. Not a sticky note on your monitor.

2. Tell Git which key to use

You've got a key. Now Git needs to know about it. Find the key ID first:

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

# Output looks like:
# sec   rsa4096/ABCD1234EFGH5678 2024-01-15
# The part after the slash is your key ID

Copy that key ID and set it in Git:

git config --global user.signingkey ABCD1234EFGH5678
git config --global commit.gpgsign true

That second line is the one most people skip. It makes Git sign every commit automatically. Set it and forget it. If you only want to sign occasionally, skip the second line and add -S to individual commits. I don't know why you'd want that ( it's more work for less security ), but you do you.

GPG key fingerprint
That long string of hex characters is your key fingerprint. Don't try to memorize it.

3. Export your public key to GitHub ( or GitLab, or wherever )

Nobody can verify your signed commits if they don't have your public key. Upload it.

gpg --armor --export ABCD1234EFGH5678 | pbcopy
# Or on Linux:
gpg --armor --export ABCD1234EFGH5678 | xclip -sel clip

Then go to GitHub Settings > SSH and GPG keys > New GPG key. Paste it. Done. If you use GitLab, same thing, different menu. The principle is always the same: export the public key, paste it into your git host.

4. Stop GPG from asking for your passphrase every single commit

This is the part that makes everyone give up on GPG signing. You type a commit, and a dialog pops up. Every. Single. Time. Fix it.

Add this to ~/.gnupg/gpg-agent.conf:

default-cache-ttl 86400
max-cache-ttl 86400

That caches your passphrase for 24 hours. You type it once in the morning and then you're done. On macOS, make sure you're using the pinentry-mac program. On Linux, use pinentry-tty or pinentry-gtk. If GPG can't find a pinentry program, it just... doesn't work. Silently. Because of course it does.

5. Verify it's actually working

Make a commit. Then check:

git log --show-signature -1

You should see "Good signature from..." in the output. If you see "Can't check signature" or "No public key", you messed up step 3. Go back. On GitHub, your signed commits get a nice "Verified" badge. That's the whole point. Anyone can claim to be you in a commit message. Only signed commits prove it.

Verified commit badge
That little green badge is the only reason to bother with any of this.

Conclusion

Five rules. Generate a real key, tell Git about it, upload the public key, fix the passphrase prompt, and verify. That's it. Everything else in the GPG manual ( subkeys, revocation certificates, key servers ) is nice-to-have. These five things are the ones that make signed commits actually work day to day.

Set it up once. Forget about it. Get the green badge. :)