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 <email@example.com> 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
You can add as many email addresses as you want using the
adduid sub-command, just remember to
save once done.
$ gpg --edit-key firstname.lastname@example.org gpg> adduid Real name: Ahmad Nassri Email address: email@example.com Comment: You selected this USER-ID: "Ahmad Nassri <firstname.lastname@example.org>" 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 <email@example.com>" 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 <firstname.lastname@example.org> [ unknown] (2). Ahmad Nassri <email@example.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
Now simply use
-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="firstname.lastname@example.org" You need a passphrase to unlock the secret key for user: "Ahmad Nassri <email@example.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
firstname.lastname@example.org address, instead you can simply configure Git to use the verified email address directly.
$ git config user.signingkey email@example.com # per repository $ git config --global user.signingkey firstname.lastname@example.org # global
You can now simply use
--gpg-sign to commit without having to provide the Key ID:
$ git commit -S
7. Use as Many Identities as you like
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@example.com" $ git commit --gpg-sign="firstname.lastname@example.org" $ git commit -S "397FECF2" # shorthand
This can also be handy if you have multiple GPG identities (e.g. Work / Personal)
Set all commits to be signed by default, no further need for
--gpg-signper commit. (Git
$ git config commit.gpgsign true # per repository $ git config --global commit.gpgsign true # global
commit.gpgSignconfiguration / force unsigned commit:
$ git --no-gpg-sign commit
To list commit log with signatures, use
$ 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@example.com>" gpg: aka "keybase.io/ahmadnassri <firstname.lastname@example.org>" Author: Ahmad Nassri <email@example.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.