Github GPG + Keybase PGP

Earlier this week, GitHub announced the addition GPG signature verification support, in the form of a badge indicating if the signature could be verified using any of the contributor’s GPG keys uploaded to GitHub.

Git itself supports signing tags and commits (as of v1.7.9) with GPG Keys, which can be used as a verification method to ensure commits are actually from a trusted source, especially if you’re taking work from others on the internet!

If you’ve never used GPG keys to sign your git commits before, the setup is pretty straightforward, and Github provides a detailed guide on the setup and usage of GPG Keys with Git & Github.

If you’re a keybase.io user as I am, there are a few gotchas to keep in mind when setting this up. This is due to the Keybase identity defaulting to keybase.io/username <username@keybase.io> which is not a verifiable address by Github.

If you attempt to sign your commits with a Keybase Key, you’ll end up with an Unverified badge on your commits:

Luckily, you can still use your Keybase.io Key on Github with a simple workaround, following the instructions below:

1. Add a new ID to your Keybase Key

Using the gpg command line tool, you can edit your Keybase key and add your verified Github email address as an additional identity.

You can add as many email addresses as you want using the adduid sub-command, just remember to save once done.

$ gpg --edit-key ahmadnassri@keybase.io

gpg> adduid
Real name: Ahmad Nassri
Email address: email@ahmadnassri.com
Comment: 
You selected this USER-ID:
    "Ahmad Nassri <email@ahmadnassri.com>"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O

You need a passphrase to unlock the secret key for
user: "keybase.io/username <username@keybase.io>"
4096-bit RSA key, ID 53A56417, created 2014-10-08


pub  4096R/53A56417  created: 2014-10-08  expires: never       usage: SCEA
                     trust: ultimate      validity: ultimate
sub  2048R/7B6D3EB9  created: 2016-04-09  expires: never       usage: E   
[ultimate] (1)  keybase.io/ahmadnassri <ahmadnassri@keybase.io>
[ unknown] (2). Ahmad Nassri <email@ahmadnassri.com>

gpg> save

You will be asked to provide a Full Name, Email, and Comment (optional), then prompted to enter your Keybase passphrase.

2. Update Keybase

Now lets make sure we sync our changes with Keybase.io servers:

$ keybase pgp update
▶ INFO Posting update for key 2378eec3437b70e26cc977d3a91e9cc653a56447.
▶ INFO Key was already up to date.

3. Export your Key

You can use the keybase CLI to export your public key:

$ keybase pgp export

Or, you can simply copy it from your Keybase profile on the web:

4. Import to Github

Add the public key into your Github Settings and you’ll note the additional verified email address is now added (you can safely ignore the Unverified warning for username@keybase.io).

5. Commit!

Now simply use --gpg-sign[=<keyid>] or -S[<keyid>] as an argument to git commit to sign your commits, you will be prompted to type your passphrase again:

$ git commit --gpg-sign="email@ahmadnassri.com"

You need a passphrase to unlock the secret key for
user: "Ahmad Nassri <email@ahmadnassri.com>"
2048-bit RSA key, ID 397FECF2, created 2014-10-08 (main key ID 53A56417)

[master d9bbac5] comment
 Date: Sat Apr 9 14:13:04 2016 -0400
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 README.md

You should be able to see the Verified badge on your commit view in Github:

6. Tell Git about your GPG key

The instructions provided by Github refer to using the GPG Key ID, which will not work in this case, as it will default to the username@keybase.io address, instead you can simply configure Git to use the verified email address directly.

$ git config user.signingkey email@ahmadnassri.com # per repository
$ git config --global user.signingkey email@ahmadnassri.com # global

You can now simply use -S or --gpg-sign to commit without having to provide the Key ID:

$ git commit -S

7. Use as Many Identities as you like

The keyid argument is optional and defaults to the committer identity or the user.signingkey variable value. It can also be used to overwrite the user.signingkey configuration per-commit:

$ git commit --gpg-sign="email@ahmadnassri.com"
$ git commit --gpg-sign="ahmad@mashape.com"
$ git commit -S "397FECF2" # shorthand

This can also be handy if you have multiple GPG identities (e.g. Work / Personal)

Tips:

Set all commits to be signed by default, no further need for -S or --gpg-sign per commit. (Git v2.0.0 and above):

$ git config commit.gpgsign true # per repository
$ git config --global commit.gpgsign true # global

Countermand commit.gpgSign configuration / force unsigned commit:

$ git --no-gpg-sign commit

To list commit log with signatures, use --show-signature:

$ git log --show-signature

commit f4e41456d0afad4bb08c80c2ed8a3c8d277b16dd
gpg: Signature made Sat 09 Apr 2016 02:11:33 PM EDT using RSA key ID 397FECF2
gpg: Good signature from "Ahmad Nassri <email@ahmadnassri.com>"
gpg:                 aka "keybase.io/ahmadnassri <ahmadnassri@keybase.io>"
Author: Ahmad Nassri <email@ahmadnassri.com>
Date:   Sat Apr 9 13:49:19 2016 -0400

    commit message

For more info on signing your work with Git, I recommend reviewing Chapter 7.4 of the official Git book.