This post discuss the use of digital signatures and how to configure Git and GitHub to sign and verify commits using GnuPG keys – also known as GPG keys.

Digital signatures and signed commits

Digital signatures are product of cryptographic protocols that provide means to authenticate the alleged authorships of signed messages. They also guarantee the integrity of signed messages, ensuring that the messages were not modified after signed 1.

Git can be configured to sign commits using a criptographic protocol such as GnuPG 2. Signed commits can be verified by anyone who knows the signer’s public key; including GitHub, which marks commits with valid signatures with a “verified” badge 3.

The following sections explain how to generate a GnuPG key pair and how to use it to sign and verify commits on Git and Github.

Generating a GnuPG key pair 4

List available GnuPG keys in your computer to see if you already have an usable key pair.

gpg --list-keys

If there is a key pair you want to use, skip to the next section. Otherwise, generate a new key pair.

gpg --full-generate-key

You will be asked to choose the cryptographic algorithm that will be used to generate the keys. As there are many of them, some of which will be replaced over time, I recommend that you just accept the options suggested by the GnuPG application. Those should be safe settings for this scenario.

You will also be asked for an expiration policy. The simplest option here is to not set an expiration term, creating a non-expirable key pair.

Then you will have to set the identity behind the signature keys. You must give a name and an email that are used both in your git config and your GitHub account. You can also add a descriptive comment.

Finally, you will choose a passphrase for your new key pair. After that, you can list your GnuPG keys again. You should see your newly created key pair.

Setting a GnuPG key on Git 2

To set your private GnuPG key on Git, you have to get its id by executing the following command.

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

The output of the above command should look like this:

sec   ed25519/2C33BE84F853D7BE 2024-03-09 [SC]
      36D3F228934F50219211F1C62C33BE84F853D7BE
uid               [   plena  ] Fulano de Tal <fulano@mail.com>
ssb   cv25519/136C603051B6AECA 2024-03-09 [E]

In the above example, the key id is 2C33BE84F853D7BE. Use the following command with your own key id to set it as Git’s signing key.

git config --global user.signingkey 2C33BE84F853D7BE

Finally, set git to always sign new commits.

git config --global commit.gpgsign true

Setting a GnuPG key on GitHub 3

To add your public key to GitHub, print and copy it by replacing 2C33BE84F853D7BE with your own key id in the following command.

gpg --armor --export 2C33BE84F853D7BE

Now go to your GitHub account settings. In the “SSH and GPG keys” section, paste and add your public key. Now GitHub will be able to verify commits signed with your private key.

Enabling vigilant mode on GitHub

Optionally, you can enable vigilant mode. This will show a “unverified” badge on any commit without a valid signature matching the identity (name and email) of its author.

Note that this configuration will also be applied to all your previous commits.

Update – Apr 28, 2024

This content also applies to other Git collaboration platforms, such as Codeberg 5.

References

  1. National Institute of Standards and Technology. Digital Signatures. Retrieved March 9, 2023 from https://csrc.nist.gov/Projects/Digital-Signatures. ↩

  2. Git. Git Tools - Signing Your Work. Retrieved March 9, 2023 from https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work. ↩ ↩2

  3. GitHub Docs. 2023. Managing commit signature verification. Retrieved March 9, 2023 from https://docs.github.com/en/authentication/managing-commit-signature-verification. ↩ ↩2

  4. GNU Privacy Guard. 2024. GPG(1). Retrieved April 28, 2024 from https://gnupg.org/documentation/manuals/gnupg24/gpg.1.html. ↩

  5. Codeberg Documentation. 2024. Adding a GPG key to your account. Retrieved April 28, 2024 from https://docs.codeberg.org/security/gpg-key/. ↩