Setting up GPG for Git Commit Signing and Authentication

This post outlines the steps I took to enable GPG and configure it for authentication and signing commits in GitHub. It’s important to note that this isn’t a simple copy-and-paste solution; you’ll need to adapt some commands with your specific key IDs and keygrips. However, if you’re comfortable working with the command line, you should be able to follow these steps with ease.

Installing GnuPG and pinentry-mac

Before you begin, you’ll need to install GnuPG and pinentry-mac on your system. If you're using Homebrew, you can install them with the following command:

$ brew install gnupg pinentry-mac

Configuring GPG Key Display

You can configure GPG to display keys in a more detailed format, including the keygrip and fingerprint, which can be useful for identifying and managing your keys. Here’s how:

$ cat >> ~/.gnupg/gpg.conf << EOF
keyid-format long
with-fingerprint
with-keygrip
EOF

Now, when you run gpg -k, it will display your keys in the long format, including the keygrip and fingerprint. This makes it easier to identify your keys and verify their authenticity.

Enabling SSH Support

To enable GPG to act as an SSH agent, you’ll need to configure it. Create or edit the file .gnupg/gpg-agent.conf and add the following lines:

$ cat >> ~/.gnupg/gpg-agent.conf << EOF
enable-ssh-support
pinentry-program /opt/homebrew/bin/pinentry-mac
EOF

This enables SSH support and sets the pinentry-program to pinentry-mac, which provides a graphical interface for entering your GPG passphrase.

Creating a Key

Next, generate a new GPG key. The --expert option gives you more control over the key generation process, and --full-gen-key ensures a complete key is created:

$ gpg --expert --full-gen-key

Follow the prompts to specify the key type, length, and expiration date. You’ll also be asked to provide your name and email address.

Adding Subkeys

For enhanced security, it’s recommended to create separate subkeys for different purposes. This allows you to revoke individual subkeys if necessary without compromising your entire key. After generating your primary key, you can add subkeys for signing, encryption, and authentication.

Start the key editing process:

$ gpg --expert --edit-key ${MASTER_KEYID}

Add a subkey:

gpg> addkey

Choose the key type: Select the appropriate key type for the subkey you want to create:

• (10) ECC (sign only) for signing.
• (11) ECC (set your our capabilities) for authentication.
• (12) ECC (encrypt only) for encryption.

Set the expiration date: Follow the prompts to set the desired expiration date for the subkey.

Repeat for other subkeys: Repeat steps 2–4 to add subkeys for other purposes.

gpg> save

This will add the subkeys to your primary key. You can now use these subkeys for their respective purposes.

Finding the Keygrip

To use your GPG key for SSH authentication, you need to find its “keygrip.” This is a unique identifier for your key. You can find it using the following command:

$ gpg -k --keyid-format long --with-keygrip

Look for the line that starts with Keygrip. The long hexadecimal string after the colon is your keygrip.

Adding the Keygrip to SSH Control

Add the keygrip to the GPG agent’s SSH control file:

$ echo ${AUTH_SUBKEY_KEYGRIP} >> ~/.gnupg/sshcontrol

Configuring SSH to Use the GPG Agent

Tell SSH how to access the GPG agent:

$ cat >> ~/.zshrc << EOF
export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket)
gpgconf --launch gpg-agent
EOF

This sets the SSH_AUTH_SOCK environment variable to the path of the GPG agent's socket file and launches the agent if it's not already running.

Listing the SSH Key

List the SSH keys available to the agent:

$ ssh-add -L

That’s it! You have now successfully configured GPG for SSH authentication with GitHub. You can now add these keys to your GitHub account to sign commits and authenticate with your repositories.

Additional Notes

If the new identity is now showing try restarting the agent:

$ gpg-connect-agent killagent /bye
$ gpg-connect-agent /bye