macOS GPG Setup for Git Commit Signing

README.md

macOS GPG Setup for Git Commit Signing

This guide explains how to configure GPG commit signing on macOS using Homebrew, ensuring your passphrase saves securely to the macOS Keychain to eliminate constant password prompts.

Prerequisites

Install GPG and the macOS pinentry graphical application via Homebrew:

brew install gnupg pinentry-mac

Step 1: Configure GPG Agent

1. Find the absolute path of your pinentry-mac installation:

   which pinentry-mac

   (Usually /opt/homebrew/bin/pinentry-mac on Apple Silicon or /usr/local/bin/pinentry-mac on Intel).

2. Create or overwrite your GPG agent configuration file (~/.gnupg/gpg-agent.conf) using that absolute path:

   # Replace the path below if your 'which pinentry-mac' output was different
   echo "pinentry-program /opt/homebrew/bin/pinentry-mac" > ~/.gnupg/gpg-agent.conf
   echo "default-cache-ttl 604800" >> ~/.gnupg/gpg-agent.conf
   echo "max-cache-ttl 604800" >> ~/.gnupg/gpg-agent.conf

Step 2: Configure Environment and Git

1. Add the GPG TTY variable to your shell profile (~/.zshrc or ~/.bash_profile):

   echo 'export GPG_TTY=\$(tty)' >> ~/.zshrc
   source ~/.zshrc

2. Find your long GPG key ID:

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

   Look for the line starting with sec. The ID is the alphanumeric string right after the slash (e.g., 3AA5C34371567BD2).

3. Link your key to Git and enable global automatic signing:

   git config --global user.signingkey YOUR_KEY_ID_HERE
   git config --global commit.gpgsign true
   git config --global gpg.program \$(which gpg)

Step 3: Apply Changes & Save Passphrase

1. Force the GPG agent to reload and read the new configurations:

   gpgconf --kill gpg-agent
   gpg-connect-agent reloadagent /bye

2. Trigger the Keychain prompt by making a test commit:

   git commit -m "test: verify automatic gpg signing"

3. When the native macOS pop-up window appears, enter your GPG passphrase and check the box to save it in your Keychain.

Troubleshooting & Verification

• Verify Signature: Run git log --show-signature -1 to confirm the commit shows a Good signature.
• Fix "No pinentry" Error: If signing fails, verify that the path inside ~/.gnupg/gpg-agent.conf matches your actual which pinentry-mac path, then run the reload commands in Step 3 again.