Sign your work on Git locally using GPG keys | Commit signature verification

6 min readJul 17, 2021

Here, I’ll show you how you can sign your commits on git using GPG keys so that they are marked as verified on GitHub and others can be confident that these commits come from a genuine source and are not been tampered with. If you don’t know about GPG keys or PGP encryption, check out this tutorial on how to set these up in Windows.

GitHub uses OpenPGP libraries to confirm that your locally signed commits are cryptographically verifiable against a public key that has been added to your GitHub account.

To sign commits using GPG and have those commits verified on GitHub, follow the steps listed below:

1. Checking if a GPG key already exists

GitHub supports several GPG key algorithms — RSA, ElGamal, ECDH, ECDSA, DSA, and EdDSA. So if you will try to add a key generated with an unsupported algorithm, you may encounter an error.

Firstly, install GnuPG command-line tools.
Install Git in your local machine.
Use this command to list the long form of the GPG keys for which you have both a public and private key(required for signing commits):

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

Check the output to see if you have an existing GPG key pair: If there are no GPG key pairs or you don’t want to use any that are available for signing commits, then you can generate a new GPG key, or If there is an existing GPG key pair and you want to use it to sign commits, then you can add it to your GitHub account. We will discuss both, below.

2. Generate a new GPG key

You can generate a new GPG key using git with any supported algorithm.

Firstly, install the GnuPG command-line tools.
Install and open Git in your local machine.
Use this command to generate a GPG key pair that uses RSA: $ gpg --full-generate-key , If you’re on version 2.1.16 or less use: $ gpg --default-new-key-algo rsa4096 --gen-key
At the prompt, specify the kind of key you want, or you can press Enter to keep the defaults.
At the prompt, specify the key size you want, or press Enter to keep the default. Your key must be at least 4096 bits.
Enter the time until which the key should be valid, or press Enter to keep the default selection, indicating that the key will not expire.
Verify whether your selections are correct and Enter your user ID information(When asked to enter your email address, ensure that you have entered the verified email address for your GitHub account).
Now, Type a secure passphrase.
Use this command to list the long form of the GPG keys for which you have both a public and private key(required for signing commits):

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

From the list of GPG keys, copy the long form of the GPG key ID you’d like to use. In this example, the GPG key ID is J639H343S4367BD2:

$ gpg --list-secret-keys --keyid-format=long
/Users/damian/.gnupg/secring.gpg
------------------------------------
sec   4096R/J639H343S4367BD2 2022-07-17 [expires: 2022-07-17]
uid                          Damian 
ssb   4096R/6JL17F4FT19E7A 2021-07-17

Use the command below, substituting the GPG key ID you’d like to use. It will print the GPG key ID in ASCII armor format. In this example, the GPG key ID is J639H343S4367BD2:

$ gpg --armor --export J639H343S4367BD2

Copy your GPG key, beginning with — — — —BEGIN PGP PUBLIC KEY BLOCK — — — — and ending with — — — — END PGP PUBLIC KEY BLOCK — — — —

3. Add a new GPG key to your GitHub account

You can add your GPG key to your GitHub account to configure it to use the key.

In the upper-right corner of GitHub UI, click your profile photo, then click Settings.
In the user settings sidebar, click SSH and GPG keys.
Now, click on New GPG key.
In the Key field, paste the GPG key you copied when you generated your GPG key in step 2.
Click Add GPG key and to confirm the action, enter your GitHub password.

4. Tell Git about your signing key

To sign commits locally, you need to inform Git that there is a GPG key available that you would like to use. You can only use a GPG key that matches your committer identity and your verified email address associated with your GitHub account, so keep this in mind. If you have multiple GPG keys, you need to tell Git which one to use using the steps listed below:

Install and open Git in your local machine.
Use this command to list the long form of the GPG keys for which you have both a public and private key(required for signing commits):

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

From the list of GPG keys, copy the long form of the GPG key ID you’d like to use. In this example, the GPG key ID is J639H343S4367BD2:

$ gpg --list-secret-keys --keyid-format=long
/Users/damian/.gnupg/secring.gpg
------------------------------------
sec   4096R/J639H343S4367BD2 2022-07-17 [expires: 2022-07-17]
uid                          Damian 
ssb   4096R/6JL17F4FT19E7A 2021-07-17

To set your GPG signing key in Git, use the command given below, substituting in the GPG key ID you’d like to use. In this example, the GPG key ID is J639H343S4367BD2:

$ git config --global user.signingkey J639H343S4367BD2

To store your GPG key passphrase so you don’t have to enter it every time you sign a commit, use the following tools:
For Windows users, the Gpg4win integrates with other Windows tools. For Mac users, the GPG Suite allows you to store your GPG key passphrase in the Mac OS Keychain.

Bonus: Signing commits locally using GPG key

If you have multiple keys or are attempting to sign commits with a key that does not match your committer identity, you should first tell Git about your signing key. After that, follow these steps:

When committing changes in your local branch, add the -S flag to the git commit command which creates a signed commit:

$ git commit -S -m <your commit message>

If you are using GPG, after you create your commit, provide the passphrase you set up when you generated your GPG key.
When you’ve finished creating commits locally, push them to your remote repository on GitHub:

$ git push

On GitHub, navigate to your pull request. On the pull request, click Commits. To view more detailed information about the verified signature, click Verified.

Bonus: Associate an email with your GPG key

If your GPG key is not associated with a GitHub verified email address that matches your committer identity. Follow these steps:

Open Git in your local machine.
Use this command to list the long form of the GPG keys for which you have both a public and private key(required for signing commits):

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

From the list of GPG keys, copy the long form of the GPG key ID you’d like to use. In this example, the GPG key ID is J639H343S4367BD2:

$ gpg --list-secret-keys --keyid-format=long
/Users/damian/.gnupg/secring.gpg
------------------------------------
sec   4096R/J639H343S4367BD2 2022-07-17 [expires: 2022-07-17]
uid                          Damian 
ssb   4096R/6JL17F4FT19E7A 2021-07-17

Enter the command given below, substituting in the GPG key ID you'd like to use. In the following example, the GPG key ID is J639H343S4367BD2:

$ gpg --edit-key J639H343S4367BD2

Now, Enter gpg> adduid to add the user ID details.
Follow the prompts to supply your real name, email address, and any comments. To keep your email address private, use your GitHub-provided no-reply email address.

Real Name: Shinchan
  Email address: shinchan@hungamatv.com
  Comment: GitHub key
  Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit?

Enter O to confirm your selections and Enter your key’s passphrase. Enter gpg> save to save the changes.
Use the command below, substituting the GPG key ID you’d like to use. It will print the GPG key ID in ASCII armor format. In this example, the GPG key ID is J639H343S4367BD2:

$ gpg --armor --export J639H343S4367BD2

Upload the GPG key by adding it to your GitHub account.

Thanks for reading, If you liked it, a 👏 will be appreciated. Have a nice day!