Setup Git Keybase.io PGP signed/verified commit

To enhance cybersecurity via signed Git commits is generally seen as a worthwhile pursuit. It’s possible to require signed / verified commits via rules at GitHub and GitLab. PGP IDs can be readily tied between GitHub, social media, website, etc. via Keybase.io–here is my Keybase profile.

Setup

This process assumes:

0. GPG install

  • Linux: apt install gnupg
  • MacOS: brew install gnupg
  • Windows:
    • setup GPG via “Git Bash”
    • or, get GPG via Kleopatra GPG binary install.

1. Get Keybase keys into GPG

Export Keybase public & private key and import into GPG:

keybase pgp export | gpg --import

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

The GPG signature will be encrypted via password you enter. This password must be distinct from your Keybase password.

2. Verify key

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

The first lines will be like:

sec   rsa4096/05F2BD2A525007DF

The hexadecimal part after the / is a 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.

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.

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

On Windows, additionally do

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

gpg --armor --export 05F2BD2A525007DF

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.