Setup GitHub Keybase.io PGP signed/verified commit

With recent cybersecurity scandals over user modules written in Python and other languages, it’s past time to employ (and even require, via per-repo GitHub Branch Rules) signed / verified commits at GitHub. PGP IDs can be readily tied between GitHub, online personality at Twitter, website, etc. via the free Keybase.io service.

Setup

This process assumes:

0. GPG install

  • Linux: apt install gnupg
  • MacOS: brew install gnupg

On Windows you can setup GPG via “Git Bash” just like Linux (easy). Or on Windows you can get GPG via Kleopatra GPG binary install.

1. Export Keybase public & private key and import into GPG:

Linux / MacOS / Windows Subsystem for Linux / Git Bash:

keybase pgp export | gpg --import

keybase pgp export --secret | gpg --allow-secret-key --import

Windows Kleopatra:

keybase pgp export > keybase-public.asc

keybase pgp export --secret > keybase-private.asc

The “keybase-private.asc” will be itself encrypted via password you enter–must be distinct from your Keybase password.

With Kleopatra, import keybase-private.asc

2. Verify key

Linux / MacOS / Windows Subsystem for Linux / Git Bash:

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

one of the first lines will be like:

sec   rsa4096/05F2BD2A525007DF

copy the hexadecimal part after the /. This is a public reference to keybase.io keypair. It’s shown on the keybase.io public profile, next to the key icon.

Windows Kleopatra:

In Kleopatra, right click the key in the list to “certify” the key. Note that the rightmost part of the fingerprint matchs the public reference to keybase.io keypair. It’s shown on the keybase.io public profile, next to the key icon.

3. Add GitHub verified email

At least one of these GitHub verified email address MUST match the [user] email in ~/.gitconfig or Unverified warnings appear on GitHub commits!

Linux / MacOS / Windows Subsystem for Linux / Git Bash:

For this example I use my GPG public ID–you use yours.

gpg --edit-key 05F2BD2A525007DF

In the interactive GPG session that launches, type

adduid

and enter Name and the Email address–which must exactly match the GitHub verified email address. I also add the @users.noreply.github.com fake email that I always use to avoid spam. Do adduid twice–once for the real GitHub verified email address and again for the github_username@users.noreply.github.com fake email.

Add “trust” from the GPG> prompt:

trust

Since it’s you, perhaps a trust level of 5 is appropriate. type

save

to save changes, which may not show up until exiting and reentering the GPG> prompt.

Windows Kleopatra:

In Kleopatra, right click the key and add email addresses via “Add User ID”. Do this twice–once for the real GitHub verified email address and again for the github_username@users.noreply.github.com fake email.

4. Configure Git to use Keybase

From Terminal / Command Prompt:

Do this using your public Keybase hex ID as seen next to the key logo on your public Keybase.io profile, not mine in the example below.

git config --global user.signingkey 05F2BD2A525007DF

git config --global commit.gpgsign true
  • Windows Kleopatra: additionally, point Git to GPG: git config --global gpg.program "C:\Program Files (x86)\GnuPG\bin\gpg.exe"

check ~/.gitconfig to see entries under [user] signingkey and [commit] gpgsign

Add the GPG public key to GitHub–copy and paste the output from this command into the GitHub New GPG Key

Linux / MacOS / Windows Subsystem for Linux / Git Bash:

gpg --armor --export 05F2BD2A525007DF

Windows Kleopatra:

Export public certificate to file and copy/paste to GitHub New GPG Key

Verify

Make a git commit after the procedure above, and see the signature notes:

git log --show-signature

it will start with

gpg: Signature made

Temporary disable signing

If you temporarily lose access to your GPG password, you won’t be able to git commit. A temporary workaround is to edit ~/.gitconfig to have

[commit]
    gpgsign = false

or simply add the --no-gpg-sign option like:

git commit -am "msg" --no-gpg-sign

Alternatively, if you prefer not signing as default, you can sign only certain commits by

git commit -S

Note that’s a capital S.

Notes

reference 1