So you were going through commits in your organisation’s repository and saw a little “Verified” badge next to the commit hash. Wondered how their commit got Verified? GitHub certainly doesn’t have a subscription that will give you a “Verified” badge like some other social media platforms. You know the one, I’m talking about.

So what does it mean? How do you get that?

Let’s explore.

What Is Git Commit Signing?

Do you remember how you configured Git on your machine? You probably ran a couple of commands like these:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Did you know that you could choose to be anyone you want when you configure git?

I could set my user.name to “Bill Gates” and my user.email to gates@gates-foundation.org and make a commit. Git wouldn’t stop me from assuming Gates’s identity. This is called identity spoofing.

  graph TD
    A[Attacker] -- "git config user.name 'Jane Doe'" --> B
    B -- "git config user.email 'jane.doe@company.com'" --> C(MaliciousCommit)
    C -- "git push" --> D(CompanyRepo)
    D -- "Looks like a valid commit from Jane!" --> E(Team)

Git commit signing is the cryptographic solution to this problem.

It is a process where you use a personal, secret key to add a unique, verifiable “signature” to every commit you make. This signature mathematically proves that the commit was created by you (or at least, by the person who has access to your secret key) and that the commit wasn’t altered since you signed it.

How Does It Work?

This “notarisation” is usually done using GPG (GNU Privacy Guard), which is an implementation of public-key cryptography.

Here’s the gist:

  1. Generate a pair, ahem, a pair of keys

    • A Private Key: This is your secret. You never share it. You keep it on your development machine, protected by a strong passphrase. This is your “signature stamp.”
    • A Public Key: This is the “key” to verify your signature. You share this with the world. You upload it to GitHub, GitLab, or give it to your colleagues.

  2. Signing the deal

    • When you make a commit, Git takes a snapshot of your changes (the commit hash).
    • It then uses your private key to sign that hash, creating a unique signature block and attaches it to the commit.

  3. Judgement time - verify the signature

    • When you push your signed commit, GitHub sees the signature.
    • It looks up the public key you uploaded to your account.
    • This key is used to unlock the signature and check if it matches the commit data.
    • If it mathematically checks out, it proves two things:
      1. The commit was signed by the only person in the world with the matching private key, hopefully, that’s just you.
      2. The commit’s contents haven’t been changed at all since it was signed.
    • …and you get that “Verified” badge. Money can’t buy everything.

Here’s how that flow looks:

  %% title: "Git Commit Signing"
graph TD
    subgraph You ["Authors Laptop"]
        A(CommitData) -- "Sign with..." --> B(EncryptedSignature)
        C(YourPrivateKey) --> B
    end
    
    subgraph GitHub ["Verification Server"]
        D(YourPublicKey) --> F
        E(EncryptedSignature) --> F(VerificationCheck)
        A2(CommitData) --> F
        F -- "Mathematically check?" --> G[Verified Badge✅]
    end

    A --> A2
    B --> E

Why Should I Sign My Commits? Does It Help?

There are so many reasons why. Let’s take a look at a few of them.

Proof of Authenticity

It proves you are who you say you are. In a world of remote work and distributed teams (like the ones I’ve managed), this is non-trivial.

Malicious Code Prevention

If someone spoofed your identity to push a commit that adds a security backdoor, steals credentials, or deletes production data. This is a very real supply chain attack. Signed commits are the first-line of defence. If a commit isn’t signed by a trusted key, it raises a red flag.

Chain of Trust

When I’m building a team that operates critical infrastructure, like the platform engineering teams or the energy commerce teams at Kaluza, I need to know exactly who contributed every line of code. It’s about accountability. If every commit is signed, we have a verifiable, unbroken chain of trust from author to production. An engineer signing their commits is a sign they take ownership and responsibility for their work.

Good Security Policies

Many organisations (and many open-source projects) require commit signing. On GitHub, you can even protect a branch by setting it to require all commits to be signed. This is a great way to ensure that your master/main branches are secure.

How Can I Start Signing My Commits?

Okay, let’s get this set up - worth investing the time.

Step 1: Install GPG

  • On macOS (using Homebrew): brew install gpg
  • On Windows: Download and install Gpg4win.
  • On Linux (Ubuntu/Debian): sudo apt-get install gpg

Step 2: Generate Your GPG Key Pair

I didn’t want to repeat what’s already been documented well, so here’s a great guide from GitHub on generating a GPG key.

Step 3: Tell Git About Your Key

This is also well documented in GitHub’s documentation

Refer Signing Commits on GitHub documentation.

Step 5: Add Your Public Key to GitHub

Follow GitHub’s guide on adding a GPG key to your account.

What If I Use a Private Email on GitHub?

This is a common “gotcha.” You’ve set up GitHub to hide your real email, and it provided you with a private “noreply” email like 123456+username@users.noreply.github.com.

What’s the problem?

GitHub’s verification checks two things:

  1. Was the commit signed by a key I trust (the one you uploaded)?
  2. Does the email in the commit (user.email) match an email address associated with the GPG key?

If your GPG key was created with jane.doe@example.com but your git config user.email is set to the noreply address, the emails won’t match, and GitHub will show the commit as “Unverified” even though the signature is valid.

The Solution

You need to add your GitHub noreply email as a second (or third, or fourth) identity to your existing GPG key.

This is also well documented in Github’s Documentation on Associating email with GPG key

It’s About the Craft

At the end of the day, signing your commits is a small habit that reinforces a bigger culture. It’s about building secure, resilient, and trustworthy systems. It’s about showing your teammates that you take accountability and security seriously.

Hope this helps. Happy (and safe) coding.

Fun fact is that you can sign your commits using other tools too, like SSH keys, but GPG remains the most widely supported and recognized method. If you use 1password, it has built-in support for managing GPG and SSH keys as well. Checkout Git commit signing using SSH Keys in 1Password 8.

Useful references