How to sign git commits and tags with GPG

In this article, we will learn how to sign git commits and tags to verify that the code actually came from you and that it wasn’t maliciously altered by an attacker while you were transferring it.

GnuPG is a complete and free implementation of the OpenPGP standard. GnuPG allows you to encrypt and sign your data and communications; it features a versatile key management system, along with access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications.

It is a common practice in software development to sign software packages to prove their authenticity. In the same way, it is possible to sign Git commits and tags, usually with GPG, to prove that the code came from you and that it wasn’t maliciously altered by an attacker.

Checkout related posts:

Ensure that you have GPG installed

GPG is a command line tool with features for easy integration with other applications. It is a free encryption software which can be used to encrypt and decrypt files. We will use it to sign our Git commits and tags. On a UNIX-like operating systems like Ubuntu and MacOS, gpg usually comes pre-installed. For windows, you have to download and install GPG yourself.

Confirm the installation by checking the version using this command:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
$ gpg --version

gpg (GnuPG) 2.2.35
libgcrypt 1.10.1-unknown
Copyright (C) 2022 g10 Code GmbH
License GNU GPL-3.0-or-later &lt;https://gnu.org/licenses/gpl.html&gt;
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Home: /home/citizix/.gnupg
Supported algorithms:
Pubkey: RSA, ELG, DSA, ECDH, ECDSA, EDDSA
Cipher: IDEA, 3DES, CAST5, BLOWFISH, AES, AES192, AES256, TWOFISH,
        CAMELLIA128, CAMELLIA192, CAMELLIA256
Hash: SHA1, RIPEMD160, SHA256, SHA384, SHA512, SHA224
Compression: Uncompressed, ZIP, ZLIB, BZIP2

If gpg doesn’t work for you, then try writing gpg2 instead and see if that works. If the gpg2 command works for you, you can tell Git to use it for signing commits with the following command:

1
git config --global gpg.program gpg2

As a matter of fact, Git doesn’t care what program you use for signing your commits as long as it works like GPG.

Configuring GPG keys

Once the gpg command is working as expected, we can generate the key pairs - similar to what we do with SSH keys.

The following command will guide you through the GPG key creation process.

1
gpg --gen-key

For more options, you can safely use the following settings:

Key type: RSA and RSA.
Size of key: 4096 bits.
Validity of key: zero (unless you want your key to expire).

1
gpg --full-gen-key

Next, GPG will ask for the following details to establish your identity. Here’s an example of the information GPG will ask for:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
$ gpg --full-gen-key
gpg (GnuPG) 2.4.5; Copyright (C) 2024 g10 Code GmbH
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Please select what kind of key you want:
   (1) RSA and RSA
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
   (9) ECC (sign and encrypt) *default*
  (10) ECC (sign only)
  (14) Existing key from card
Your selection? 1
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (3072) 4096
Requested keysize is 4096 bits
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0) 0
Key does not expire at all
Is this correct? (y/N) y

GnuPG needs to construct a user ID to identify your key.

Real name: Eutychus Towett
Email address: kipdev25@gmail.com
Comment: My Main GPG Key
You selected this USER-ID:
    "Eutychus Towett (My Main GPG Key) <kipdev25@gmail.com>"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: directory '/Users/eutychus/.gnupg/openpgp-revocs.d' created
gpg: revocation certificate stored as '/Users/eutychus/.gnupg/openpgp-revocs.d/DF1C7C152C816E6B5BFBF8EC979DC53554748B64.rev'
public and secret key created and signed.

pub   rsa4096 2024-09-05 [SC]
      DF1C7C152C816E6B5BFBF8EC979DC53554748B64
uid                      Eutychus Towett (My Main GPG Key) <kipdev25@gmail.com>
sub   rsa4096 2024-09-05 [E]

If you are planning to use different email addresses on different projects, you’ll have to generate one GPG key for each email address.

GPG will also ask you to create a password for the key. You’ll be prompted for this password whenever you try to use your key. I’d recommend choosing a strong and memorable password.

Important: Make sure you keep your GPG keys safe, especially the private key.

In order to put your GPG keys to use, you will need access to your key ID and the public key. We’ll see how to get those in the sections below.

Listing GPG Keys

Once you have setup a number of GPG keys, you might want to see a list of all your keys. You can do that with the following command:

List all GPG public keys

1
gpg --list-keys --keyid-format long

List all GPG secret keys.

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

For our example in this tutorial, we’ll only see the keys for a particular identity. We do this by appending an email address to the end of one of the above commands:

1
2
3
4
5
6
7
8
9
$ gpg --list-secret-keys etowett@citizix.com

gpg: checking the trustdb
gpg: marginals needed: 3  completes needed: 1  trust model: pgp
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
sec   rsa4096 2022-05-17 [SC]
      8527AA1318C42445DC08C06ED722AF52CA1CE58C
uid           [ultimate] Eutychus Towett (Main GPG Key) &lt;etowett@citizix.com&gt;
ssb   rsa4096 2022-05-17 [E]

If you run the command without the email parameter, you will see all your GPG keys.

Getting GPG key ID

To get the ID of your GPG key, use the command above to see a list of keys first. Now, focus on the line that says sec, i.e. rsa4096 2022-05-17 [SC]. The part after the below that is the GPG key ID. For example: 8527AA1318C42445DC08C06ED722AF52CA1CE58C.

Getting GPG public key

To see the public key, you need to have a key ID as mentioned above. Use the following command to see your full public key:

The syntax is: gpg --armor --export KEY-ID

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
$ gpg --armor --export 8527AA1318C42445DC08C06ED722AF52CA1CE58C

-----BEGIN PGP PUBLIC KEY BLOCK-----

mQINBF1xnckBEADIeAmeXUAtUJ5EHr/xwpzNU1C/NixbaHnmFhgnMa076OpbJxvP
kpOGciSN9a4xn39soxFY56G3rO3R7ecANBXjsTi+sz4CzKxU6OH2Eu1tJnidLVg2
# ...
aPA1Ij+YjJ+2QOcFDU0+fSTYv+SYAmLsmDK9Fqib9yUjTQgTau8hslBS3YhzlAxK
szXI7gyqWSwNWbvkpJtnR/1eLh/CRC5pFX62AvpnJbqnistNY8OpYCV+kzvwjEiL
=gAQS
-----END PGP PUBLIC KEY BLOCK-----

Deleting GPG Keys

If you ever want to remove a public or private key, you need to run one of the following commands depending on your needs:

Deletes GPG secret key.

1
gpg --delete-secret-key etowett@citizix.com

Deletes GPG public key for an email

1
gpg --delete-key etowett@citizix.com

When deleting, start with the private key

Configuring Git

Now, we need to tell Git about our GPG keys to be able to sign and verify things.

Add GPG keys to Git repository manager

Most Git repository managers like GitHub, GitLab and BitBucket provide an option to add GPG public keys to your account. The option to add your GPG public key to your Git repo manager is usually under profile settings.

Run the command gpg --armor --export KEY-ID to get your GPG public key and add it to your repository manager. These keys are then used to generate badges to indicate if your commits are verified. This lets your team members easily check if your commits are signed and hence, authentic.

Add GPG keys to Git command-line tool

Use the following command to tell your command-line tool to use a specific GPG key for signing your commits:

The syntax is git config user.signingkey KEY-ID

1
git config user.signingkey 8527AA1318C42445DC08C06ED722AF52CA1CE58

You can use git config --global user.signingkey KEY-ID to save this in your global Git settings which will then be used for all projects.

1
git config --global user.signingkey 8527AA1318C42445DC08C06ED722AF52CA1CE58

Signing Commits

Now that the GPG keys are in place, it’s actually time to sign commits and tags!

Please note the key to use to sign. You can get by listing the key and grabbing ID, 10630F587CF32D001E3ED7591442DEFCB04678A3 in my case.

1
2
3
4
5
6
7
$ gpg --list-keys --keyid-format long
[keyboxd]
---------
pub   rsa4096/121DC46759398B64 2024-09-05 [SC]
      10630F587CF32D001E3ED7591442DEFCB04678A3
uid                 [ultimate] Eutychus Towett (My Main GPG Key) <etowett@citizix.com>
sub   rsa4096/4227AC936746EBD0 2024-09-05 [E]

Signing Git commits

To create a signed commit, add the additional parameter -S to your git commit command like this:

1
git commit -S -m "Enough about you, let's talk about me, Johnny Bravo."

Doing this will show you a dialog where you will have to enter your GPG password to sign and make the commit.

Signing Git tags

To create a signed tag, add the additional parameter -s to your git tag command like this:

1
git tag -s v1.19

Doing this will show you a dialog where you will have to enter your GPG password to sign and make the commit.

Always sign Git commits

If you’ve decided that you always want to sign your commits and tags, then you can update your git configuration accordingly with the following command:

Enable signing for the project.

1
git config commit.gpgsign true

Enable signing globally.

1
git config --global commit.gpgsign true

Conclusion

Signing GPG commits is an extra layer of security that help verify if a commit or a tag was actually made by you. This can be done by generating a key and configuring it with Git. Signed git commits usually have a “verified” badge on Git repository managers like GitHub, GitLab, BitBucket, etc.