🔧 Git -> GitHub -> GPG Key (Windows)

If you're a beginner to Git or just starting to tinker with GitHub and GPG, you're probably here because you want to get that super-cute green "Verified" label next to your commits. The one that makes your contributions look professional and trusted. But, like most of us, you might have run into a few snags while setting up GPG keys on Windows. Don’t worry—you're not alone!

In this guide, I'll walk you through the entire process of setting up GPG for signing your GitHub commits on Windows. Plus, I’ll show you how I fixed a few tricky issues along the way. So, grab your coffee, and let's dive into it.

Step 1: Install Git Bash

Before we get into the GPG configuration, let's talk about Git Bash. Git Bash is a terminal emulator that comes with Git for Windows. If you haven’t installed it yet, do yourself a favor and install it. You can get it from the official Git website. Git Bash is much more user-friendly for these kinds of setups, and it plays better with Unix-based commands that you’ll need for GPG (like export).

Using Git Bash throughout this process will save you from some headaches, especially when working with environment variables. Trust me, you’ll thank me later.

Once you've installed Git Bash, open it up. Now, you're ready to go!

Step 2: Install GPG4Win (and GPG)

To get started with GPG, you’ll need to install GPG4Win, which is the suite that includes everything you need to generate your keys. You can download it from here.

After installation, make sure GPG is accessible by running the following command in Git Bash:

gpg --version

This should return the version number of GPG if it’s properly installed. If you get an error, go back to the installation and make sure it went smoothly.

Step 3: Generate a GPG Key

Next, let’s generate your GPG key. This is the key that will be used to sign your Git commits.

1. Run the following command in Git Bash to create your GPG key:

   gpg --full-generate-key

1. Choose the default options (RSA and RSA, key size 4096, etc.), and when asked for your name and email, use the same email that you have registered with GitHub.

You should see something like this:

   Real name: Your Name
   Email address: [email protected]

Important: Make sure the email you enter matches the one on your GitHub account. If it doesn't, GitHub won’t be able to associate your commits with your account.

1. Once the key is generated, list your keys to find the key ID:

   gpg --list-secret-keys --keyid-format LONG

This will output a long string with your key ID. It should look something like this:

   sec   rsa4096/XXXXXXXXXXXXXXXX 2024-12-01 [SC] [expires: 2027-12-01]
         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   uid                 [ultimate] Your Name <[email protected]>
   ssb   rsa4096/XXXXXXXXXXXXXXXX 2024-12-01 [E] [expires: 2027-12-01]

Copy your key ID from the rsa4096/XXXXXXXXXXXXXXXX part. You'll need it for later.

Step 4: Add Your GPG Key to Git

Now that your GPG key is ready, let's tell Git to use it for signing commits. First, export the public key to add it to GitHub:

gpg --armor --export [email protected]

This will print your public GPG key in ASCII format. Copy the entire output (starting with -----BEGIN PGP PUBLIC KEY BLOCK----- and ending with -----END PGP PUBLIC KEY BLOCK-----).

Next, add this key to GitHub:

1. Go to your GitHub account and navigate to Settings > SSH and GPG Keys > New GPG Key.
2. Paste your public key into the box and save it.

Step 5: Configure Git to Use Your GPG Key

Let’s tell Git to use your GPG key when signing commits. Run the following command in Git Bash:

git config --global user.signingkey your-key-id

Replace your-key-id with the GPG key ID you copied earlier.

Then, configure Git to automatically sign your commits by default:

git config --global commit.gpgSign true

This ensures that every commit you make will be signed automatically.

Step 6: Test Your Setup

You’re almost there! Now, let’s test if everything is working properly. Try making a commit in any of your repositories:

1. Make a small change to a file and commit it:

   git commit -m "Test commit"

1. Push the commit to GitHub:

   git push

1. Check GitHub. If everything is set up correctly, you should now see the "Verified" label next to your commit on GitHub!

Common Issues & Fixes

Okay, so you followed all the steps, but you’re still facing some issues? I’ve been there, and I’ve got you covered with a couple of extra fixes.

Problem 1: "No 'Verified' label?" – Even After Everything Looks Fine

The Issue:

If you’re getting the GPG key to work locally but don’t see the "Verified" label on GitHub, there’s a chance the problem lies in how you're using the terminal.

The Fix:

In Windows, PowerShell can be tricky when it comes to handling environment variables like GPG_TTY, which is necessary for GPG to function properly. The solution is to either set the environment variable correctly in PowerShell or switch to Git Bash.

Here’s what worked for me:

1. In PowerShell, set the GPG_TTY environment variable with this command:

   $env:GPG_TTY = "COM1"

Alternatively, you can point directly to the gpg.exe executable:

   $env:GPG_TTY = "C:/Program Files (x86)/GnuPG/bin/gpg.exe"

1. Switch to Git Bash (if you're still facing issues). Git Bash works more naturally with Unix-style commands, including setting environment variables with export. In Git Bash, run:

   export GPG_TTY=$(tty)

This should resolve most issues with signing commits in Git.

Problem 2: GPG Errors on Windows – "No Secret Key"

The Issue:

This error usually means Git can’t find your GPG private key for signing commits.

The Fix:

1. Check where GPG is installed using:

   where gpg

This should show you the path to your gpg.exe. Make sure it's pointing to the correct version, usually located in C:\Program Files (x86)\GnuPG\bin\gpg.exe.

1. Configure Git to use the correct GPG version:

If Git is pointing to the wrong GPG version, set it explicitly with:

   git config --global gpg.program "C:/Program Files (x86)/GnuPG/bin/gpg.exe"

1. Double-check your GPG key with:

   gpg --list-secret-keys --keyid-format LONG

Make sure your key appears. If it doesn’t, you’ll need to import it into your keyring.

Wrapping Up

Setting up GPG on Windows for GitHub commit signing can be a bit tricky, but once you’ve got everything in place, it’s totally worth it to see that “Verified” label next to your commits.

Just remember to use Git Bash to avoid some of the headaches with PowerShell and to set the correct environment variables. If you're running into GPG errors or issues with secret keys, double-check your paths and keys, and you should be good to go!

Happy coding, and enjoy the satisfaction of seeing your verified commits on GitHub! If you have any other issues or tips to share, drop a comment or tweet at me. Let's make this process smoother for everyone.

My Social Links: LinkedIn | GitHub | 𝕏 (formerly Twitter) | Substack | Dev.to | Hashnode