Signing Commits
For higher security and identity verification we encourage everyone interacting with our GitHub repository to setup automatic commit signing using the GPG key.
Since we are using Keybase.io for secure communication you can use its ability to generate a new GPG key and use it. If you already have a GPG key that you are actively using feel free to use that key for signing your GitHub commits.
Prerequisites
You will need to install the following tools:
You should already have the second installed at this point. To install GPG pick a package manager of your choice. For example, on MacOS you can do the following:
brew install gpg
Setting up GPG Key using Keybase
This section describes how to create a new GPG key using Keybase.
Sign in to Keybase
You need to be signed in to Keybase in order to proceed. You can check if you are by running the following command:
keybase whoami
If you are not, then use the following command to log in:
keybase login
Create the GPG Key
To create a new GPG key run the following command:
keybase pgp gen --multi
Follow the instructions and respond to questions, such as:
- Your real name that should be publicly visible
- Public e-mail addresses (include the ones used for GitHub access)
- Should the key be encrypted (yes)
The output of the command should look similar to the following one:
Enter your real name, which will be publicly visible in your new key: Rafał Kuć
Enter a public email address for your key: r.kuc@solr.pl
Enter another email address (or <enter> when done): rafal@archipelo.co
Enter another email address (or <enter> when done):
Push an encrypted copy of your new secret key to the Keybase.io server? [Y/n] y
When exporting to the GnuPG keychain, encrypt private keys with a passphrase? [Y/n] y
▶ INFO PGP User ID: Rafał Kuć <r.kuc@solr.pl> [primary]
▶ INFO PGP User ID: Rafał Kuć <rafal@archipelo.co>
▶ INFO Generating primary key (4096 bits)
▶ INFO Generating encryption subkey (4096 bits)
▶ INFO Generated new PGP key:
▶ INFO user: Rafał Kuć <r.kuc@solr.pl>
▶ INFO 4096-bit RSA key, ID 8B5DC3EB465063EF, created 2022-08-05
▶ INFO Exported new key to the local GPG keychain
At this point your key should be exported to GPG, to verify that run the following command:
gpg --list-secret-keys --keyid-format LONG
The output should look like this:
/Users/rafalkuc/.gnupg/pubring.kbx
----------------------------------
sec rsa4096/8B5DC3EB465063EF 2022-08-05 [SC] [expires: 2038-08-01]
DDC427A225712CC57673FC248B5DC3EB465063EF
uid [ unknown] Rafał Kuć <r.kuc@solr.pl>
uid [ unknown] Rafał Kuć <rafal@archipelo.co>
ssb rsa4096/465F408D8D11CED0 2022-08-05 [E] [expires: 2038-08-01]
This means that your new key is visible to GPG.
Add the Public GPG Key to GitHub
You need to export your GPG public key and add it to GitHub. To do that you need to first export the key from Keybase using the following command:
keybase pgp export -q <keyID>
Where keyID is the key identifier (in my case 8B5DC3EB465063EF). You can see it in the output of the
command used to generate the key.
Go to GitHub Settings, click the New GPG key and paste the output of the above command there.
Automatically Sign Commits
Once the key is added to GitHub, you can configure your GitHub client to sign your commits automatically:
git config --global user.signingkey 8B5DC3EB465063EF
git config --global commit.gpgsign true
You can verify that everything works by running:
echo test | gpg --clearsign
To verify that your commits are signed, just create a new branch, push a commit and look
at the list of commits in that branch. You should see a Verified mark associated
with the commit:
Using Multiple Machines
When using multiple machines you can use the same GPG on all of them, the only thing is to have the GPG key imported on all of them.
On the machine that you would like to import the key to, run the following command to list the available keys:
keybase pgp list
You will see the output similar to the following one:
Keybase Key ID: 0101a18815480978d0d3cbf79c497f1a4ef78e7010c24c6f15efaf240ffa726c28dd0a
PGP Fingerprint: ddc427a225712cc57673fc248b5dc3eb465063ef
PGP Identities:
Rafał Kuć <r.kuc@solr.pl>
Rafał Kuć <rafal@archipelo.co>
Note the PGP Fingerprint - you will need it for the next commands.
The public and the private keys need to be imported to GPG, you can do it using the following commands:
keybase pgp export -q ddc427a225712cc57673fc248b5dc3eb465063ef | gpg --import
keybase pgp export -q ddc427a225712cc57673fc248b5dc3eb465063ef --secret | gpg --allow-secret-key-import --import
Finally, you need to edit the key and give it the ultimate trust, to do that run the following command:
gpg --edit-key ddc427a225712cc57673fc248b5dc3eb465063ef
You will be shown the GPG console:
gpg (GnuPG) 2.3.7; Copyright (C) 2021 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Secret key is available.
sec rsa4096/8B5DC3EB465063EF
created: 2022-08-05 expires: 2038-08-01 usage: SC
trust: unknown validity: unknown
ssb rsa4096/465F408D8D11CED0
created: 2022-08-05 expires: 2038-08-01 usage: E
[ unknown] (1). Rafał Kuć <r.kuc@solr.pl>
[ unknown] (2) Rafał Kuć <rafal@archipelo.co>
Run the trust command there:
gpg> trust
sec rsa4096/8B5DC3EB465063EF
created: 2022-08-05 expires: 2038-08-01 usage: SC
trust: unknown validity: unknown
ssb rsa4096/465F408D8D11CED0
created: 2022-08-05 expires: 2038-08-01 usage: E
[ unknown] (1). Rafał Kuć <r.kuc@solr.pl>
[ unknown] (2) Rafał Kuć <rafal@archipelo.co>
[ unknown] (3) Rafał Kuć <gr0@gr0.dev>
Please decide how far you trust this user to correctly verify other users' keys
(by looking at passports, checking fingerprints from different sources, etc.)
1 = I don't know or won't say
2 = I do NOT trust
3 = I trust marginally
4 = I trust fully
5 = I trust ultimately
m = back to the main menu
Choose the 5 as the option.
Finally, configure your GitHub client to use the GPG key similarly to what you did earlier when generating the key.
Configure cache TTL
By default, passphrase for the key is cached for a very small amount of time. The user configuration of GnuPG can be used to increase this time.
The default-cache-ttl option sets the timeout (in seconds) after the last GnuPG activity (so it resets if you use it), the max-cache-ttl option sets the timespan (in seconds) it caches after entering your password. The default value is 600 seconds (10 minutes) for default-cache-ttl and 7200 seconds (2 hours) for max-cache-ttl.
Create file ~/.gnupg/gpg-agent.conf and add next 2 lines to it:
default-cache-ttl 86400
max-cache-ttl 86400
Restart gpg-agent after that:
gpgconf --kill gpg-agent
gpg-agent --daemon
Upon success, there will be no output from these commands.
After this, GnuPG will cache your passphrase and will ask you to provide it only after 24h of inactivity or from the last time you've entered it.
Troubleshooting
The list of common issues.
GPG failed to sign the data
When you try to sign your commits GPG returns the following errors:
error: gpg failed to sign the data
fatal: failed to write commit object
In such case, try the following command:
export GPG_TTY=$(tty)
GPG Inappropriate ioctl for device
If you created a GPG with the passphrase, the passphrase prompt might fail from inside the IDE.
It'll produce the following error while signing or checking the sign with echo test | gpg --clearsign:
gpg: signing failed: Inappropriate ioctl for device
gpg: [stdin]: clear-sign failed: Inappropriate ioctl for device
To resolve this issue, you can test the signing from the Terminal outside the IDE following these simple steps:
- Close your IDE
- Open terminal
echo test | gpg --clearsign- Use your passphrase
It will allow you to push changes and use GPG key from the editor for some time. GPG without the passphrase will let you avoid this issue, but it comes with a risk of the unprotected key.
Error with pinentry
If your GPG client reports error with pinentry make sure you have it installed and added
to the GPG configuration file.
For MacOS you can follow the steps:
brew install pinentry
Next, find the path for the pinentry by running the following command:
which pinentry
Which should result in the following output:
/usr/local/bin/pinentry
Edit the ~/.gnupg/gpg-agent.conf file and add the following entry:
pinentry-program /usr/local/bin/pinentry
After doing the change you need to run the following command:
gpgconf --kill gpg-agent