Rationale

Signing commits with GPG adds another layer of security to GitHub flow.

While access to the repos is secured by your SSH key, this is only a transport authentication. Signing commits with GPG provides a proof of your identity as well as commit contents integrity.

While SOC 2 doesn't explicitly state "you must sign your commits," it provides auditors with strong, automated evidence that we are adhering to our own policies. Compliance tools have built-in tests to enforce signed commits. Branch protection rules in GitHub can require commit signing.

Actions to Take

1. Create a GPG key pair and add the public key to GitHub. Enable "Vigilant mode".
2. Enable commit signing on your machine and tell Git which key to use.
3. macOS: Add you GPG key passphrase to macOS KeyChain, so you don't have to enter it every time.

Note: On Ubuntu, step 3. is not required — the passphrase will be saved to Keyring automatically.

After this setup no additional actions should be required for the commits to be signed.

TL;DR

If you are familiar with the procedure and wish to skip the long read, here is the short version of the manual. Otherwise, please follow the sections below.

# 1. Get the key
gpg -K --keyid-format=long
# OR
gpg --full-generate-key
# Then add the public key to GitHub
gpg --armor --export <KEY ID>

# 2. Enable signing
git config --global user.signingkey <KEY ID>
git config --global commit.gpgsign true
git config --global tag.gpgSign true

# 3. Save to KeyChain
brew install pinentry-mac
touch ~/.gnupg/gpg-agent.conf
echo 'pinentry-program /opt/homebrew/bin/pinentry-mac' >> ~/.gnupg/gpg-agent.conf

Setup

Install the tools:

brew install gnupg
brew install pinentry-mac

Git calls GPG, which tries to ask you for a passphrase of your GPG key on your current terminal. On macOS, GPG is not aware what the current terminal is, so you may see an error saying gpg: signing failed: Inappropriate ioctl for device. This is solved by doing the following:

export GPG_TTY=$(tty)

Add this line to your ~/.zshrc for future use.

Tell GPG what tool to use to get the passphrase:

nano ~/.gnupg/gpg-agent.conf
# Add this line at the end:
pinentry-program /opt/homebrew/bin/pinentry-mac
# Ctrl+X, Y to save.

Restart the GPG agent after editing the config:

gpgconf --kill gpg-agent

Add GPG Key

List the GPG keys you already have:

# List the keys you have
gpg -K --keyid-format=long

If you wish to generate a new key:

gpg --full-generate-key

Note: the email in the GPG key must match your committer email in git config.

Using the GitHub Noreply Email

There are two options:

1. You may use any verified email from your GitHub account,
2. Or you may use the noreply email that GitHub provides for such purposes.

Your noreply email can be found in the email settings. Use it without the numeric part. I.e. I use [email protected] without the 5172598+ bit. (This is a counterintuitive feature that confuses a lot of people.)

If you choose to use the noreply email, you may also want to turn on the Block command line pushes that expose my email switch at the bottom of the settings page. Also, make sure the Keep my email addresses private box is checked.

In any case, make sure that the email in git config matches the one you have in your GPG key:

# To see what you have configured:
git config --global user.email

# To set the committer email:
git config --global user.email <COMMITTER EMAIL>

Adding the Key to GitHub

Once you have the key, print out its public part.

# List the keys
gpg -K --keyid-format=long

# Find the one you want to use in the list, use its key ID
gpg --armor --export <KEY ID>

For example, the output shows this:

sec   ed25519/35F67BE174274258 2025-09-24 [SC] [expires: 2026-09-24]
      C5CEE16C17CFADDC601081AA35F67BE174274258
uid                 [ultimate] Michael A. <[email protected]>
ssb   cv25519/7385308B052A2F25 2025-09-24 [E] [expires: 2026-09-24]

35F67BE174274258 is the key ID in the above printout. Use this ID to get the public key.

Add the key to your GitHub account in the settings.

Enable Vigilant mode at the bottom of the settings page.

Enable Commit Signing

Tell git which key to use for signing:

git config --global user.signingkey <KEY ID>

Finally, enable signing in git globally:

git config --global commit.gpgsign true
git config --global tag.gpgSign true

macOS: Save Passphrase to KeyChain

The first time you commit with the new signature, you should see a dialogue. Make sure the box "Save in KeyChain" is ticked.

Now, when you commit, git history will show the signature and GitHub UI will reflect it.

This is how you can check your signed commit:

git --no-pager show --pretty=fuller --show-signature