If you've ever tried setting up commit signing with GPG on GitHub and ended up scratching your head, especially on Mac? You're not alone.

You follow the official docs, generate a key, link it to GitHub, and set it up in your local repo, but your commits still show as "Unverified." That’s exactly what happened to me, and here’s how I finally got it working.

Generating Your GPG Key

The first step is generating the GPG key, which is usually pretty straightforward:

1. Generate the key:

   gpg --full-generate-key

1. Find your key ID:

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

1. Export the key:

   gpg --armor --export YOUR_KEY_ID > my-gpg-key.asc

1. Add the key to GitHub: Copy the output from the previous command and go to GitHub Settings > SSH and GPG keys > New GPG key. Paste it in there.

Once this is done, tell Git to use this key for signing commits:

git config --global user.signingkey YOUR_KEY_ID
git config --global commit.gpgSign true

That should take care of the basics. At this point, every commit you make should be signed with your GPG key.

But Is It Working? Check Your Repo’s Config

I thought I was all set until I started seeing "unverified" commits again. Here’s the thing: While you may have set the global config for commit signing, each repository has its own individual config. So, even if your global settings are correct, you still need to check the specific repo configuration.

Run the following to check if commit signing is enabled for your current repo:

git config commit.gpgSign

• If the output is true, you're good to go.
• If it’s false (or if there’s no output), you need to enable it with:

git config commit.gpgSign true

It’s a small step, but if it's not set, Git won’t sign your commits in that repo, even if you’ve got everything else configured correctly.

Don’t Want to Type Your Passphrase Everytime? Cache It!

If you’re signing commits frequently, typing your GPG passphrase every single time can get old. The good news is, you can cache the passphrase for a certain period, so you don’t have to re-enter it every time you make a commit.

To do this, add these lines to your ~/.gnupg/gpg-agent.conf file:

default-cache-ttl 600
max-cache-ttl 7200

This will cache your passphrase for 10 minutes, and the maximum cache time will be 2 hours. After that, GPG will ask you for your passphrase again.

GPG Not Working? Try Restarting the GPG Agent

Sometimes things can just break for no reason. You might notice that keys stop working, commits aren’t signed, or you see weird errors. When this happens, one thing that tends to help is restarting the GPG agent.

You can do that with:

gpgconf --kill gpg-agent

This command forces the GPG agent to restart the next time you use it. It’s a simple fix but can clear up a lot of problems when things go sideways.

GitHub Desktop Issues: No Passphrase Prompt or "Signing Failed"

If you’re using GitHub Desktop and facing issues with GPG signing (like not getting a passphrase prompt, or encountering the error gpg: signing failed: No such file or directory), the issue might be related to how GitHub Desktop interacts with GPG.

The Problem

GitHub Desktop may not properly launch the passphrase entry dialog for your GPG key, or it might not find the GPG agent. This can result in errors like:

gpg: signing failed: No such file or directory
fatal: failed to write commit object

Solution

1. Install pinentry-mac: GitHub Desktop often requires the pinentry-mac program for handling the passphrase prompt. Install it using Homebrew:

   brew install pinentry-mac

1. Configure GPG to Use pinentry-mac: Next, make sure GPG uses the right pinentry program by adding this line to your ~/.gnupg/gpg-agent.conf file:

   echo "pinentry-program $(which pinentry-mac)" >> ~/.gnupg/gpg-agent.conf

1. Restart the GPG Agent: After updating the configuration, restart the GPG agent to apply the changes:

   gpgconf --kill gpg-agent

1. Check GPG Version: Ensure you're using GPG version 2+, as older versions don’t support modern features like pinentry-mode loopback:

   gpg --version

If you have an older version, update GPG with:

   brew install gnupg

Once you’ve done this, try again in GitHub Desktop. You should now be prompted for your passphrase, and commits will be signed correctly.

If You’re Still Stuck

If you continue to encounter issues, you might want to try signing a commit directly from the terminal to isolate whether the issue is with GitHub Desktop or your GPG setup:

git commit --amend --no-edit --gpg-sign

If this works but GitHub Desktop still doesn’t, the issue is likely specific to GitHub Desktop's interaction with GPG.

Wrapping Up

Getting GPG commit signing set up on GitHub can be a bit of a pain, especially when things don’t work as expected. But once it’s up and running, it’s a great way to ensure the authenticity of your commits. Here’s a quick checklist to make sure everything’s working:

• Check your repo’s commit.gpgSign config: Make sure it’s set to true for your repo with git config commit.gpgSign.
• Cache your passphrase: Use gpg-agent to avoid entering your passphrase every time.
• Restart the GPG agent: If things go wrong, use gpgconf --kill gpg-agent to reset your keys.
• For GitHub Desktop users: Install pinentry-mac and configure GPG to use it to resolve issues with the passphrase prompt and signing failures.

If you’re still running into issues, or if you’ve got a better way of managing GPG with GitHub, leave a comment. I’d love to hear your thoughts!

Thanks for reading. May the code be with you!

My Social Links: LinkedIn | GitHub | 𝕏 (formerly Twitter) | Substack | Dev.to | Hashnode