Commit Signature Verification for GitHub

Using GPG (GNU Privacy Guard), you can sign your tags and commits, and they will appear as verified, which gives other people confidence that the changes made to that repository came from a trusted source.

You can use GPG to sign commits with a key you generate on your machine. GitHub supports several GPG key algorithms:

• RSA
• ElGamal
• DSA
• ECDH
• ECDSA
• EdDSA

As from official GitHub documentation:

GitHub uses OpenPGP libraries to confirm that your locally signed commits and tags are cryptographically verifiable against a public key you have added to your account on GitHub.

Generate a GPG key

Before generating a GPG key, you will have to install the GPG CLI, which I strongly encourage you to do through HomeBrew.

brew install gnupg

Now that you have it installed, run the interactive command below, which will prompt you to enter some details.

gpg --full-generate-key

• Enter 1 - For RSA and RSA
• Enter 4096 - For the most bits
• Enter 0 - For the key to never expire
• Enter y - To confirm the entry

Now it persists in asking some basic questions, but these are very important, as they need to match your GitHub profile details. You'll need to enter your full name and e-mail address.

Important note: If you have enabled "Keep my e-mail addresses private" in your GitHub Account Settings, you will have to enter the e-mail address that GitHub provides instead. You can view that e-mail address within your GitHub's Account E-mail Settings, but in my case, it's the dvlden@users.noreply.github.com (where dvlden represents the GitHub username), so I can assume that's how it is for everyone.

I am using this hidden e-mail feature of GitHub, as it's an excellent addition to privacy. Your e-mail will be publicly visible in your verified commits; hence, I suggest you use it too.

Once you complete these steps, you must enter a secure passphrase required for commit verification. Of course, it isn't enjoyable to type this passphrase every single time, so at the end of this setup, I'll also tell you how to securely store the passphrase in your KeyChain and never type it again.

Retrieve the GPG key

Now is the time to retrieve a public key that you must add to your GitHub Settings.

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

You should see an output similar to this:

sec   rsa4096/BBBDC36A74E4B56C 2022-07-09 [SC]
      BA6C83ECE7BF6F9B9377D7B6BBBDC36A74E4B56C
uid                 [ultimate] Nenad Novakovic <dvlden@users.noreply.github.com>
ssb   rsa4096/EF744DC319071C7F 2022-07-09 [E]

Copy the long form of the GPG key, defined at the sec but exclude the key algorithm, which is rsa4096. From the example output, that would be BBBDC36A74E4B56C.

Run the following command and replace the sample ID with yours. It will copy your public key to the clipboard...

gpg --armor --export BBBDC36A74E4B56C | pbcopy

Add the GPG key to the GitHub account

Go to your GitHub Settings and navigate to SSH and GPG keys to add your GPG key. Then, click the button in the GPG keys section to add a new key. Paste it and confirm; you'll have to enter your GitHub account's password for this change to take effect.

Let the Git know about your GPG key

For this to work, we will need that key ID again. In our example that was BBBDC36A74E4B56C.

We'll need to run two more commands. These are to let Git know about our GPG key by adding it to the global Git configuration on our machine.

git config --global commit.gpgsign true
git config --global user.signingkey BBBDC36A74E4B56C

If you are unsure whether you configured your Git for the user you entered while generating the GPG key, you can always check manually within your machine's ~/.gitconfig file. Or you can override it through the Terminal with these commands.

git config --global user.name "Nenad Novakovic"
git config --global user.email "dvlden@users.noreply.github.com"

Save your secure passphrase to the KeyChain

As promised, at the end of this GPG setup, I'll teach you how to securely store your passphrase in the KeyChain and let it handle the otherwise manual overhead.

For this to work, we will install another binary executable on our machine. We're going to work with HomeBrew again.

brew install pinentry-mac

Now we'll configure the GPG agent to use it by running the following command:

echo "pinentry-program $(which pinentry-mac)" >> ~/.gnupg/gpg-agent.conf

Finally, let's run one more command so that we get a prompt to enter our secure passphrase and get it saved in our KeyChain.

echo "test" | gpg --clearsign

Finally! You configured your machine to sign all your commits automatically from now on.