Signing Your Work

Git has the notion of defined authorship for commits and tags. This is done at either a repository or global level, using the git config command. This allows Git, and in turn sites like Github, to recognize who authored what changes to code. But config settings in plain text only go so far. Much like (regular) email, really anyone can impersonate you. Nothing can stop someone from putting your name and email in their Git config. All of a sudden you’d see commits that “you” authored which you know were in fact not you.

There is a way to get around this issue, and confirm authentic authorship, should you want a more certain way of letting people know that you authored code in certain commits. You can use a GPG/PGP key to digitally sign commits and tags. This means that though anyone could impersonate your name and email, someone could only digitally sign commits as you if they got ahold of your private key, a much larger challenge than merely editing a text file.

I have set this up on my Macs, and wanted to document the process here for future reference and in case anyone else wants this higher bar of certainty on their Git commits. The following sections describe the necessary, and optional, steps to getting this set up.

Git Version

Only versions of Git >= 2 have the GPG signing features. macOS High Sierra should have a sufficient version, but I recommend installing Git via Homebrew anyway (brew install git) to always have the latest release if you’re a serious user of Git. An advantage of the Homebrew Git install is that it comes with the git-prompt script, which allows you to show Git info in your command line prompt. Additionally, this will put the version of Git you’re using within the same paths as the GPG software.

GPG Tools

While you can install GPG software on the Mac via Homebrew, I recommend installing the free GPG Suite. A word of caution, you should customize the install and uncheck the GPGMail plugin for Apple’s Mail app. Even if you intend to digitally sign or encrypt email (which I don’t) you can still use the systemwide Services to sign or encrypt email contents, and the plugin has caused problems with composing mail for me in the past.

After the install finishes it should automatically open the GPG Keychain app and ask you to generate your GPG key. If you already have a key you can cancel this and import your existing key. But I’m assuming you don’t have a key for the purposes of this post. As soon as it has generated your key it should open the main window. At this time I highly recommend exporting your public/secret keypair to a secure location for safekeeping (but more on that, too, later).

It is worth going to System Preferences and opening the newly added GPG Suite prefpane. You should check that your key is the default, and I find it safe enough to let it store key passwords in the macOS Keychain (but that one is up to you). You can change any of these preferences to your liking.

gitconfig

You’ll need to add some information to your global gitconfig file in order to tell Git about GPG. Open that file and add the following:

[commit]
	gpgsign = true
[gpg]
	program = /usr/local/MacGPG2/bin/gpg
[user]
	signingkey = { your key id, found in Details drawer of GPG Keychain }

You should now be able to commit to any repo and that commit will be digitally signed using your GPG key. In order to confirm that the commits are now being signed use git log --show-signature to have the log also display signature information.

gpg.conf

While Git from the command line will now be able to sign all commits and tags, you need to add one line to your ~/.gnupg/gpg.conf file to allow IDEs (like Xcode) to do so. Just add no-tty to the bottom of the file and save it. Now Xcode will no longer only give you a fatal error when trying to commit.

GPG and Github

Now that you are digitally signing your commits you need to tell Github about your key so it can verify commit authenticity. To do so go into your Github settings, and choose SSH and GPG keys. That’s right, the same place you’ve come to add SSH keys you now go to add your GPG key. You can export your public key, open the file in a text editor, and copy the key block from there. From here on out, any signed commits of yours will show a green “Verified” label, both to you and others on the project.

Note that, unfortunately, Bitbucket Cloud does not currently support showing GPG and signed commit information.

Publishing your Key

It is a good idea, though optional, to publish your key. GPG Keychain can do this by sending the key to the network of public keyservers using the option for it under the Key menu. You can also simply put your public key block somewhere on your website. Facebook also allows you to add your public key to the Contact Information section of your profile. You can, of course, also email it to people or send it along like any other attatchment using any service.

Since trust is behind the strength of GPG keys, it is important that your public key is accessible to others. Just make sure that you keep the secret key close and secure. Mine is only in the keyrings on the Macs I use, and one export file that is encrypted and secured in a safe place.

keybase.io

Recently I found the Keybase website and software. This is a system that gives you a public profile (link is to my own profile), and lets you publish your GPG key, and verified ownerships of other online profiles and websites. Though totally unnecessary to use GPG to sign Git commits, Keybase can be a home for verified identities and sharing your GPG key. Further, it provides truly end-to-end encrypted storage and chat for yourself, teams, and between individuals, as well as digitally signed public folders. All based on the GPG key technology. Keybase actually has its own entire Mac app and command line interface, but you still need the regular GPG software to use your key with Git (and having it makes sense anyway so the key is usable in normal ways). So, Keybase is a collection of tools to help connect people who have GPG keys.

Conclusion

This post gives the briefest overview of how to set up Git to digitally sign Git commits. You can look through Git docs to learn more, including how to sign tags. If you follow the first sections you’ll have a key, so it suggests further uses regarding sharing that key. GPG is still quite complex, so won’t be used by that many who aren’t very good with technology (though Keybase’s hope is to change that) at this time. But it is a useful thing to know about and use, if not for all possible uses, so that if you have a more important need of it you’ve already begun learning.