Set Up Signed Commits on GitHub

A quick guide to setting up commit verification using a GPG key.

GitHub verification badge.

Acknowledgement

This article merely collates information from the following sources:

1. Adding a GPG key to your GitHub account
2. Generating a new GPG key
3. How to understand the gpg failed to sign the data problem in git

For more information and troubleshooting, please visit these sources as they contain additional guidance which may be helpful for operating systems other than macos.

The Scenario

You need to set up commit verification on your computer for the first time. Possibly you have changed computer and need to quickly set up once more. You are on macos with access to the terminal.

What you’ll need:

• macos
• Your GitHub username
• The Email address associated with your GitHub account
• Access to the command line via Command Line Interface (CLI)
• A secure password wallet

Instructions

1. In terminal, run:

terminal

git config --global commit.gpgsign true
git config --global tag.gpgsign true

2. Visit GPG suite and download the installer.
3. Follow the installation steps and quit the screen that attempts to create a new key
4. In terminal, create a key with:

terminal

gpg --full-generate-key

5. At the prompt, accept the default values for key type, size and persistence
6. Ensure you enter your real name, as it appears on GitHub, under your GitHub profile avatar. Use the primary Email associated with your GitHub account.
7. Enter a passphrase, confirm it and store it in a secure password wallet. You will need it again in the final step of this process
8. Print out the long format of the key details with:

terminal

gpg --list-secret-keys --keyid-format=long

9. Copy the long form of the key ID from the example output labelled as <COPY THIS BIT ONLY>, do not include the preceeding forward slash:

$ gpg --list-secret-keys --keyid-format=long
/Users/hubot/.gnupg/secring.gpg
------------------------------------
sec   XXXX/<COPY THIS BIT ONLY> 2023-10-23 
uid                          your username
ssb   xxxXXXX/XXXXXXXXXXXXXXXX 2023-10-23

10. Adjust this command with your copied key ID and run in terminal:

terminal

git config --global user.signingkey <INSERT YOUR KEY ID>

11. Paste your key ID into the command below and execute in terminal:

terminal

gpg --armor --export <INSERT YOUR KEY ID>

11. Copy the output, including the -----BEGIN PGP PUBLIC KEY BLOCK----- and -----END PGP PUBLIC KEY BLOCK----- sections.
12. Go to the GPG Keychain app, it should have detected the key in your clipboard and ask you to import the key to your keychain. Click OK
13. Over to your web brower, go to GitHub profile pic settings SSH and GPG keys
14. Add a new key to your account, give it an appropriate title and paste the key from your clipboard
15. GitHub will ask you to authenticate in order to make this change
16. Now ensure Git knows where to look for your GPG program:

terminal

where gpg

Copy the path to the GPG program.

17. Update the command below with the path in your clipboard:

terminal

git config --global gpg.program "<INSERT/PATH/HERE>"

18. Check that your git config file looks as expected:

terminal

git config --global --list 

Example output:

user.name=<YOUR GITHUB USERNAME>
user.email=<YOUR PRIMARY GITHUB EMAIL>
user.signingkey=<YOUR GPG KEY ID>
commit.gpgsign=true
gpg.program=<PATH TO YOUR GPG PROGRAM>
tag.gpgsign=true

19. The next time you need to commit, you will be asked to enter the passphrase you saved to your password wallet in order to add the key to your keychain

Troubleshooting

gpg: signing failed: Inappropriate ioctl for device

Add the below to your initialisation file (eg ~/.zshrc or equivalent):

~/.zshrc

GPG_TTY=$(tty)
export GPG_TTY

Restart your terminal. Try to commit once more. You’ll be asked for the GPG passphrase that you stored in your password wallet.

fin!