Why sign

A signed commit cryptographically attests "this commit was authored by the holder of this key, unchanged since signing." Signatures defend against impersonation and tampering, and platforms like GitHub display a "Verified" badge when the signature matches a configured key.

One-time setup

gpg --full-generate-key       # choose RSA 4096 or Ed25519
gpg --list-secret-keys --keyid-format=long
git config --global user.signingkey 0xABCDEF1234567890
git config --global commit.gpgsign true
git config --global tag.gpgsign true

Export the public key and add it to GitHub/GitLab/Gitea:

gpg --armor --export 0xABCDEF1234567890

Signing on demand

git commit -S -m "Important change"
git tag -s v1.0.0 -m "Release 1.0.0"

Verify a single commit or all log entries:

git log --show-signature
git verify-commit <sha>
git verify-tag v1.0.0

GPG agent and pinentry

Set up gpg-agent with a long cache so you do not retype passphrases per commit:

# ~/.gnupg/gpg-agent.conf
default-cache-ttl 28800
max-cache-ttl 86400
pinentry-program /usr/local/bin/pinentry-mac

Hardware keys

YubiKey or similar tokens can hold the GPG signing key, requiring a touch per commit. After provisioning, ensure gpg --card-status recognizes the device. The flow is identical to software keys but with hardware-backed non-exportability.

Smudge: WSL and SSH

If you sign from WSL or over SSH, configure the agent forwarding correctly. Set GPG_TTY=$(tty) in your shell init so pinentry can prompt.

Common mistakes

Setting commit.gpgsign true without a working agent makes every git commit hang on a stalled pinentry. Test interactively first. Forgetting to publish your public key to the platform leaves "Unverified" badges. Keys expire; calendar a reminder. Rebases re-sign commits with the rebaser's key, not the original author's — preserve verification carefully on shared branches.

Verify a remote push

git push --signed

Sends a signed certificate of the push intent — useful in regulated environments to prove who pushed what when.

Related

See "SSH signing (Git 2.34+)" for an easier alternative without GPG.