Setting up git GPG commit signing on macOS

Signing your git commits is the best way to prevent impersonation attacks.

Setting up git GPG commit signing on macOS
Photo by Shahadat Rahman / Unsplash

Signing your git commits is the best way to prevent impersonation attacks. Let's dive into setting it up via GPG.

Installing GPG

You're going to need Homebrew. Get it here if you don't already have it installed.

Install GPG and pinentry-mac via brew

brew install gpg2 gnupg pinentry-mac
Brew installation command

Ensuring it doesn't break

Sometimes GPG stomps its feet and cries out something about “tty” and “invalid” but the following instructions would shut it up.

Set pinentry-mac as the desired pin entry program:

# Make the directory
mkdir ~/.gnupg

# Tells GPG which pinentry program to use
echo "pinentry-program $(brew --prefix)/bin/pinentry-mac" > ~/.gnupg/gpg-agent.conf

# Secure the directory permissions
chmod 700 ~/.gnupg

# Kill agent to load the new config
killall gpg-agent
Setting up pinentry for GPG

Creating your keypair!


Run gpg --full-gen-key to pull up the key generation tool. Follow the choices made below (apart from the personal details).

# Key Type; RSA & RSA
Please select what kind of key you want:
   (1) RSA and RSA (default)
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
  (14) Existing key from card
Your selection? 1

# Key Size; 4096
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (3072) 4096

# Validity; 0
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0) 0

# Confirm Selection; y
Key does not expire at all
Is this correct? (y/N) y

# Personal Details
GnuPG needs to construct a user ID to identify your key.

Real name: Test User
Email address: test@fakedomain.faketld
Comment: Workplace Key
You selected this USER-ID:
    "Test User (Workplace Key) <test@fakedomain.faketld>"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
Generating key pair

Exporting your ID

After the generation of your keys above, run gpg -K --keyid-format SHORT to get a list of your key IDs.

Copy your key ID and fingerprint, respectively. Follow the following example to decipher the output.

# Example output
sec   rsa4096/058B1DC9 2020-10-21 [SC]
# Your key ID would be

# And your key fingerprint would be
Example key extraction from output

Exporting your Public Key

With the ID from before, run the following command gpg --armor --export [Key ID].

You should see an output similar to this;


Example PGP Public key block output

Copy the entire block, from the first dash of the BEGIN text to the last dash of the END text.

This is what you will paste in your GitHub (Or your preferred version control cloud hosting platform) settings.

Setting up Git

Configure signing program

Run the following command to set the default GPG program for git;

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

Configure signing key

Using your key fingerprint from way earlier, run the following command

git config --global user.signingkey [Key Fingerprint]

Configure signing behaviour

For best practice, run the following command to enable signing all commits by default (as opposed to having to type the -S flag for each command).

git config --global commit.gpgsign true

Setting up GitHub

GPG Key settings page on GitHub
  • Paste your public key from earlier, click on Add GPG key
    (Complete security verification, if necessary)
GPG Key registration form on GitHub
  • Enable “Vigilant mode”
Vigilant mode setting on GitHub

Using it!

When you perform a commit (e.g. git commit -S -m "Commit Message Here"), you'll be prompted by the pinentry-mac prompt for your key password. Only after a successful authentication will the commit be signed and ready to go!

Set up commit signing for VS Code

Open up your user preferences UI (⌘ + ,) and enable the Git: Enable Commit Signing option!