Signing Git Commits with GPG

GPG (GNU Privacy Guard) Setup and Usage Guide

What is GPG?

GPG (GNU Privacy Guard) is a cryptographic tool that allows users to encrypt and sign data, providing authentication and integrity verification. It is commonly used for secure email communication and verifying the authenticity of Git commits.

---

Installing GPG

MacOS

On MacOS, install GPG using Homebrew:

brew install gnupg

After installation, verify it with:

gpg --version

Windows

On Windows, install GPG by downloading Gpg4win from https://gnupg.org/download/. After installation, verify it by opening a command prompt and running:

gpg --version

---

Generating a New GPG Key

To create a new GPG key for signing Git commits, run:

gpg --full-generate-key

Follow the prompts:

• Key type: Select RSA and RSA (default)

• Key size: Enter 4096 for maximum security

• Expiration: Choose a duration (e.g., 1y for one year)

• User ID: Provide your real name and email address

• Passphrase: Enter a secure passphrase to protect your key

After generation, list your keys with:

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

Find the newly created key and note the key ID, which appears as:

sec   rsa4096/XXXXXXXXXXXXXXXX  YYYY-MM-DD [SC] [expires: YYYY-MM-DD]

---

Configuring Git to Sign Commits

Set Your GPG Key in Git

Replace XXXXXXXXXXXXXXXX with your actual key ID:

git config --global user.signingkey XXXXXXXXXXXXXXXX

Enable automatic signing of commits:

git config --global commit.gpgsign true

To verify your configuration:

git config --global --list | grep signingkey

Export Your Public Key

To use the GPG key for GitHub or other services, export it:

gpg --armor --export XXXXXXXXXXXXXXXX

Copy the output and add it to GitHub → Settings → SSH and GPG keys → New GPG Key (GitHub Link).

---

Testing GPG Signing with Git

To test your setup, create and sign a commit:

echo "Test GPG signing" > testfile

git add testfile
git commit -S -m "Test commit with GPG signing"
git push

If successful, GitHub will display a "Verified" label next to the commit.

---

Additional GPG Commands

Listing GPG Keys

To list your keys:

gpg --list-keys

To list secret (private) keys:

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

Backing Up Your GPG Key

To back up your private key:

gpg --export-secret-keys --armor XXXXXXXXXXXXXXXX > private-key-backup.asc

Store this file securely.

To back up your public key:

gpg --export --armor XXXXXXXXXXXXXXXX > public-key-backup.asc

Importing a GPG Key

To import a key from a file:

gpg --import path/to/keyfile.asc

Revoking a GPG Key

If a key is compromised or lost, revoke it:

gpg --gen-revoke XXXXXXXXXXXXXXXX > revoke.asc

Then, import the revocation certificate:

gpg --import revoke.asc

---

Troubleshooting

Check if the GPG Agent is Running

If you encounter issues signing commits, restart the GPG agent:

gpgconf --kill gpg-agent

gpgconf --launch gpg-agent

Ensure Git is Using the Correct GPG Program

Run:

git config --global gpg.program $(which gpg)

For GPG version 2.x, set:

git config --global gpg.program gpg2

Manually Sign a File to Test GPG

echo "test" > testfile.txt

gpg --clearsign testfile.txt

If successful, this generates a signed file testfile.txt.asc.

---

Conclusion

Setting up GPG for Git signing ensures the integrity and authenticity of commits. By following this guide, developers can securely sign commits and contribute to repositories with verified identities.