Development

How to configure GitHub GPG signing

Gamunu Balagalla

— 3 min read
How to configure GitHub GPG signing

GPG (GNU Privacy Guard) is a tool that allows you to sign and encrypt your data using public-key cryptography. Signing your git commits with GPG ensures that anyone who receives your code can verify that it was authored by you and not tampered with by someone else. GitHub supports GPG signature verification for commits and tags.

In this blog post, I will show you how to configure GitHub GPG signing on your local machine and on your GitHub account. I will assume that you have already installed git and gpg on your system.

Generating a new GPG key

The first step is to generate a new GPG key pair, which consists of a public key and a private key. The public key can be shared with others, while the private key must be kept secret and protected by a passphrase.

To generate a new GPG key pair, open your terminal and run the following command:

gpg --full-generate-key

This will prompt you to choose the type of key, the key size, the expiration date, and the user ID information. For GitHub GPG signing, you should choose RSA as the type of key, 4096 bits as the key size, no expiration date (or any date that suits your needs), and an email address that matches your verified email address on GitHub. You can also enter your name and a comment if you wish.

For an example:

Please select what kind of key you want:
(1) RSA and RSA (default)
(2) DSA and Elgamal
(3) DSA (sign only)
(4) RSA (sign only)
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: Gamunu Balagalla
Email address: [email protected]
Comment: Personal GitHub GPG Key
You selected this USER-ID:
"Gamunu Balagalla (Personal GitHub GPG Key) <[email protected]>"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O

You need a Passphrase to protect your secret key.
Enter passphrase: **********
Repeat passphrase: **********

After entering a secure passphrase, gpg will generate your new GPG key pair. You can list your keys with the following command:

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

This will show something like this:

/Users/gamunu/.gnupg/pubring.kbx
---------------------------------
sec rsa4096/123456789ABCDEF0 2023-03-18 [SC]
FEDCBA987654321001234567123456789ABCDEF0
uid [ultimate] Gamunu Balagalla (Personal GitHub GPG Key) <[email protected]>
ssb rsa4096/0123456789FEDCBA 2023-03-18 [E]

The long form of the GPG key ID is `123456789ABCDEF0`, which is located after `rsa4096/` on the `sec` line. You will need this ID later.

Adding your public GPG key to GitHub

The next step is to add your public GPG key to your GitHub account so that GitHub can verify your signed commits and tags. To do this, you need to copy your public GPG key from your terminal and paste it into GitHub.

To copy your public GPG key from your terminal, run the following command with your long form of the GPG key ID:

gpg --armor --export 123456789ABCDEF0 | pbcopy # Mac OS X only; use xclip or xsel for Linux systems; use clip for Windows systems.

This will copy your public GPG key into the clipboard in ASCII-armored format.

To paste it into GitHub, follow these steps:

  • Log in to your GitHub account and go to Settings > SSH and GPG keys > New GPG Key.
  • Paste the public key you copied into the Key field.
  • Click Add GPG Key.
  • Enter your GitHub password to confirm.

Configure Git to use your GPG key for signing

Now that you have added your GPG key to GitHub, you need to tell Git which key to use for signing. You can do that by setting the user.signingkey config option.

git config --global user.signingkey 123456789ABCDEF0

where `123456789ABCDEF0` is the fingerprint of your key.

Enable auto-signing for all commits

If you want Git to automatically sign all your commits by default, you can set the commit.gpgsign config option. 

git config --global commit.gpgsign true

Alternatively, if you only want to sign some of your commits manually, you can use the `-S` flag when running the `git commit` command .

For example:

git commit -S -m "My signed commit message"

Verify signed commits on GitHub

After pushing your signed commits to GitHub, you can verify them by looking at the “Verified” badge next to each commit. You can also click on it to see more details about the signature.

That’s it! You have successfully configured the git config with gpg key and allowed auto signing for all or some of your commits.

Read more