Using GPG to Sign Git Commits

Sign commits and verify authorship using GPG keys.

Modern software development relies on collaboration and code provenance. When multiple contributors work on a project, it's essential to verify that commits genuinely originate from those they claim. One way to guarantee authorship and tamper-evidence is by signing commits using GPG (GNU Privacy Guard) keys. This blog post walks you through why and how to set up GPG-signed commits in Git, as well as how to verify them.

Why Sign Git Commits?

Trust: Signing commits cryptographically proves that the commit was made by the person who owns the GPG key.
Integrity: Signed commits show that their contents haven’t been tampered with after signing.
Verification: Platforms like GitHub, GitLab, and Bitbucket recognize and display signatures, helping reviewers quickly verify the legitimacy of contributors.

Prerequisites

Git installed (git --version)
GPG installed (gpg --version)
An account on a code hosting platform (GitHub, GitLab, Bitbucket, etc.)

1. Generate a GPG Key

If you don't already have a GPG key, generate one:

gpg --full-generate-key

Select RSA and RSA or EdDSA keys for best compatibility.
Choose a key size, ideally 4096 bits for RSA.
Set the expiration date.
Enter your name and email (should match the email used in your Git commits).
Set a strong passphrase when prompted.

List Your Keys

Once generated, list your keys to find the key ID:

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

You'll see an output similar to this:

/home/username/.gnupg/secring.gpg
---------------------------------
sec   rsa4096/ABCDEF1234567890 2024-06-01 [SC]
      Your Name <you@example.com>

The part after rsa4096/ is your key ID (ABCDEF1234567890).

2. Add GPG Key to Git

Tell Git to use your new GPG key to sign commits:

git config --global user.signingkey ABCDEF1234567890

Replace ABCDEF1234567890 with your key ID.

Optionally, set Git to sign all your commits by default:

git config --global commit.gpgsign true

Ensure Git knows how to call GPG. For GPG 2.x, instruct Git to use gpg2 if needed:

git config --global gpg.program gpg

3. Export and Share Your Public Key

To verify signatures, collaborators need your public key. Export and share it:

gpg --armor --export you@example.com

Copy the output and share it or upload it to a keyserver:

gpg --keyserver hkps://keys.openpgp.org --send-keys ABCDEF1234567890

On GitHub and similar platforms, add your public GPG key under your account’s settings (e.g., GitHub > Settings > SSH and GPG keys > New GPG key).

4. Sign a Commit

To sign a commit explicitly:

git commit -S -m "Your commit message"

Or, with default signing enabled, any git commit will sign automatically.

If prompted, enter your GPG key passphrase.

5. Push and Verify Signed Commits

On the Command Line

To check the signature of commits:

git log --show-signature

Or for a specific commit:

git show --show-signature <commit-hash>

You'll see signature and verification details in the log.

On Git Hosting Platforms

Services like GitHub, GitLab, and Bitbucket display the commit signature status. For example, on GitHub you’ll see a "Verified" badge next to signed commits.

6. Troubleshooting

GPG-Agent Issues: If you’re asked for your passphrase often, install a GPG agent (gpg-agent). Use gpg --use-agent.
Key Not Found? Double-check that your commit email matches the email on your GPG key.
Pinentry Dialogs: Issues on Windows and macOS can sometimes be resolved by installing GPG Suite (macOS) or Gpg4win (Windows).
Compatibility: Some older versions of Git require extra configuration, such as adding export GPG_TTY=$(tty) inside your .bashrc or .zshrc.

Conclusion

Signing your Git commits with GPG enhances trust and accountability in your software projects. With just a few commands, you can ensure your contributions are verifiably yours, building credibility with your team and the open source community.

Further reading:

Secure your commits—sign them with GPG!