Hey, Rafael!

Signing Git commits with GPG using Keybase


Rafael Fonseca

Rafael Fonseca

howto git gpg

Signing Git commits with GPG using Keybase

Posted by Rafael Fonseca on .

howto git gpg

Signing Git commits with GPG using Keybase

Posted by Rafael Fonseca on .

GitHub recently announced support for signing commits using a GPG key. This provides an extra layer of security when verifying changes made to a repository come from valid users.

Setting up GPG is super easy with Keybase, so I won't repeat the instructions here. If you don't have a Keybase account yet, set yourself up. If you need an invite, ask me on Twitter or via the comments.

Note: Steps described here are performed on OS X. YMMV

Additional emails in the GPG key

By default, Keybase will generate a GPG key for you during setup that does not contain any valid email addresses you normally use, instead generating a key for username@keybase.io. If you normally make Git commits from username@domain.com, GitHub will show those commits as Unverified.

To fix that, we need to edit the GPG key to include other email addresses. Log into Keybase from your machine and check that your key ID shows up in GPG with:

gpg --list-keys

If your key does not appear (you should look for your Keybase username in the list), you can import it with these instructions.

For example, mine showed up as (in this post, my key ID is BB12C3BF; yours will be different, and you should replace mine with yours on all these instructions):

pub   4096R/BB12C3BF 2014-07-13
uid                  keybase.io/rfonseca <rfonseca@keybase.io>

With your key ID handy, let's add some emails:

gpg --edit-key BB12C3BF # swap with your key id

You'll get a new prompt similar to this:

gpg (GnuPG) 1.4.20; Copyright (C) 2015 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Secret key is available.

pub  4096R/BB12C3BF  created: 2014-07-13  expires: never       usage: SCEA
                     trust: unknown       validity: unknown
[ unknown] (1)  keybase.io/rfonseca <rfonseca@keybase.io>


To add additional emails (identities), type adduid and press [ENTER]. You'll be asked for your name, email address and comments, along with a confirmation dialog. Repeat this step for as many emails as you have registered with GitHub.

Once all details have been entered, type save and press [ENTER] to close GPG and save your changes. The last step is to export your public key with:

gpg --armor --export BB12C3BF

And add it to your GitHub profile as per these instructions.

Telling Git to always sign commits

Configure git to always sign commits on your machine with your GPG key:

git config --global commit.gpgsign true
git config --global user.signingkey BB12C3BF

The end result is that commits made from this machine will show up in GitHub like this (check the Commits page):
Properly signed commit

Bonus: Set up gpg-agent

One of the downsides of extra validation is that we need to enter our GPG passphrase for every single commit we make. This can get quite tiresome.

To counter that, we can use a tool called gpg-agent. It acts similarly to ssh-agent in that it caches the keys in memory, providing a socket that git and gpg use to communicate for key storage/retrieval. I wired it up so that it asks me for my passphrase:

  • once when I open iTerm 2 and attempt to save a commit
  • once after 600 seconds have passed without any commits made

To set it up, install gpg-agent via Homebrew:

brew install gpg-agent

Ensure gpg-agent uses a standard socket to allow git and gpg to communicate with it by adding the following to ~/.gnupg/gpg-agent.conf:


Add the following to your profile (~/.profile) to ensure the GPG_AGENT_INFO variable is loaded into your environment:

# gpg-agent
[ -f ~/.gpg-agent-info ] && source ~/.gpg-agent-info
if [ -S "${GPG_AGENT_INFO%%:*}" ]; then
  export GPG_TTY=$(tty)
  eval $( gpg-agent --daemon --write-env-file ~/.gpg-agent-info )

Uncomment the line with # use-agent from your ~/.gnupg/gpg.conf to allow gpg to use the agent.

Edited on 19/04/2016: simplified the setup for automatically starting the GPG agent.

Edited on 20/04/2016: added missing command to set GPG_TTY to ~/.profile.

Edited on 08/05/2017: corrected --export argument for gpg command

Happy GPGing!

Rafael Fonseca

Rafael Fonseca

View Comments...