October 27th, 2018

Verified (signed) commits on GitHub

How did you end up here? Either you want to setup signing of commits, or you were just wondering what that "Verified" badge on GitHub meant. To be honest, I just noticed the badge when one of my pull requests got merged and kinda liked it.

But what is it really? A short explanation from the GitHub blog;

When you’re building software with people from around the world, sometimes it’s important to validate that commits and tags are coming from an identified source. Many open source projects and companies want to be sure that a commit is from a verified source. GPG signature verification on commits and tags makes it easy to see when a commit or tag is signed by a verified key that GitHub knows about.

Setting it up

So now we know what it is, how do you get it? Whether or not you need it is something else and for you to decide. But basically it will require you to entire your password whenever you sign a commit.

Generating a GPG key

If you're on mac, you probably want to install latest GPG binaries using homebrew.

brew install gpg

Once you have the latest gpg tools installed you can generate a key using the following command.

gpg --full-generate-key

Follow the instructions and accept the defaults, for the max key length Github recommends not going above 4096. When asked for your email address, make sure you enter your verified Github email.

Exporting public GPG key & adding to GitHub

After the process completed you can check if everything went well by running the following command. This will output a list of GPG keys, copy the GPG key id, in this case E0FDB38622C5CF52.

gpg --list-secret-keys --keyid-format LONG

Now run the following command with your GPG key id you copied earlier to export the public key. Copy the output (your public key) and add it to your GitHub account.

gpg --armor --export E0FDB38622C5CF52

Configuring git

Last step is to configure git locally on your machine so it knows about your signing key. Run the following command, again substitute the key id with the one you copied earlier.

git config --global user.signingkey E0FDB38622C5CF52

You also want to add the following to your ~/.bash_profile, ~/.profile or ~/.zshrc file - depending on what you using. I use ZSH so I added it to my ~/.zshrc file at the end.

export GPG_TTY=$(tty)

Usage

To sign a specific commit, e.g. for a release, just add the -S flag in your command (you can use the same flag for signing tags). You will be prompted to enter the password used when generating the GPG key. Git won't ask everytime for the password though, I (think) once you entered your password it keeps a session open for ~15 minutes. If you commit again signed it will prolong this session.

git commit -S -m ":memo: Updated readme"

If you push now your signed commit you will see it pops up on GitHub with a verified badge next to it.

Bonus

Enable autosigning of commit globally can be done using the following command. Note that this will sign all commits for all your different projects, and thus will require you to enter your password often.

git config --global commit.gpgSign true

Or if you want just all your tags/releases signed run the following command.

git config --global tag.gpgSign true

That's it!