↓Skip to main content

Signing Code Commits

·3 mins
Table of Contents

We should always sign the commits that we make in source code repositories, especially for shared projects like Open Source software. This ensures that every commit includes a signature that links it to a specific author. Since I use more than one repository hosting service, I have written this article on how to set up commit signing in a way that works across services.

This method uses GnuPG, the current standard Open Source tool for signing code commits. Sequoia PGP may supersede GnuPG in future.

GPG: Many existing documents use the term GPG instead of GnuPG or OpenPGP. To avoid confusion, this article follows the same convention.

How Commit Signing Works #

If you use a repository hosting service like Codeberg, GitHub or an instance of GitLab, you will see that it can show commits as Verified. This means that it has successfully checked the signature on the commit. Git can also verify signed commits.

GitHub and GitLab allow you to sign commits with SSH keys. Avoid using SSH keys to sign commits, because the SSH key standard does not support verification or revocation of keys across independent and distributed systems.

To sign your commits, create a keypair with GPG and configure Git to use it. Once you do this, Git can automatically sign every commit and tag that you make. The private key in the keypair stays on your device. You publish the public key, so that other systems can use it to verify signed items.

Register the public key with the hosting services that you use, so that they can verify your commits. If you work on Open Source projects, publish your GPG public keys to open key servers as well. This enables other people to verify your commits without relying on the hosting service.

The rest of this article leads you through the process to enable commit signing.

Installing GPG #

Many Linux distributions automatically include GPG. To install GPG on macOS, use Homebrew. Run these commands to install GPG and integration with the desktop:

brew install gnupg
brew install pinentry-mac

Creating a GPG Key #

To create a GPG key, run the gpg command in a terminal window, like this:

gpg --full-gen-key

GPG will prompt you for information. Use these values:

  • Select the RSA and RSA algorithm
  • Choose a key length of 4096
  • Accept the default option to have no expiry date for your key
  • Enter the same email address that you will use for code hosting sites, such as Codeberg or GitHub

Once you have created a GPG key, configure Git to use it.

First get the ID of the key:

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

This displays an output like this:

pub   rsa4096/C36CB86CB86B3716 2022-01-18 [SC]
      BF18AC2876178908D6E71267D36CB86CB86B3716
uid                 [ultimate] Anne Example <anne@example.org>
sub   rsa4096/B7BB94F0C9BA6CAA 2022-01-18 [E]

In this example, the key ID is C36CB86CB86B3716.

Enabling Git to Sign Commits #

To configure Git to use the key that you have created:

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

Registering Your GPG Key with Repository Hosts #

Add your GPG key to your accounts on code hosting services that you use. These services each provide their own documentation on how to register your GPG key:

Publishing Your GPG Key to Key Servers #

If you work on Open Source projects, publish your GPG public key to the OpenPGP key server. If you contribute to an existing project, you might also publish your GPG public key to other servers that the project recommends. This enables other people to verify your commits without relying on a hosting service.