tpwo.github.io

A personal blog

Use SSH key to sign your Git commits

Written on (updated )

But why?

You might wonder why should you sign your commits. This is a valid question, and some people just don’t care about it. If you don’t have a ready opinion[1], I’ll try to convince you.

Choose your warrior committer

In Git you can assign any author to any commit. This is a basic functionality of Git, you can put any name and email in .gitconfig or pass one-time name/email with -C when committing (or set ENV variables etc. – there are many ways).

Make GitHub to link their profile

Then, you can push this commit to GitHub. If the commit email address is already used by someone on GitHub, GitHub links it with their profile. Even if this is obviously not their commit. GitHub cannot know this.

Fork their repo and display fabricated commit from the base URL

You might think that no one cares about you doing some fake commits in your repos. But you can fork any repo and fake commits in the fork.

Then, you can display a commit from fork even when looking at it from the original repo. Actually, this is a big problem with GitHub UI, as it treats all forks to be connected with the base repo.

I once found a fabricated Linus Torvalds commit in which he deleted the whole Linux codebase with a funny commit message.

Unfortunately, I haven’t found it now but here’s something similar (also from Torvalds!).

TLDR: fabrication process is simple:

  1. Fork a repo
  2. Create a fake commit.
  3. Display it in context of the original repo. GitHub allows for that!

What can I do?

You cannot prevent people from using your (public) email and fabricate commits on your account. But you can turn on GitHub vigilant mode which is described in their docs.

Then all of your unsigned commits will be marked explicitly as unverified. Unfortunately, also all of your own commits, prior you started to sign them, will be marked as well.

Old times

Nevermind, let’s go back to the original topic. When you wanted to sign your commits in Git a few years ago, you were forced to use GPG. Unless you already have and use GPG, it was a lot of pain. GPG is quite old, and it doesn’t offer the best user experience. Using it, meant maintaining another key, which you have to protect with another strong password and back it up. This was enough to stop many people from signing their commits.

Alternative to GPG

By the end of 2021 with v2.34.0 Git added a way to sign your commits using SSH keys. I tried switching to SSH a few years ago but it didn’t work, and quick research showed that I’m not the only one.

Out of curiosity I checked it now, and I was able to sign my commits after a few minutes of configuration, and this post is the result of that. Time heals wounds!

Configure Git

I assume that you already have and use a password-protected SSH key[2]. Then you can tell Git to use it:

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/<your-public-key>

And that’s all! To sign a single commit:

git commit -S -m 'Your commit message'

To always sign your commits:

git config --global commit.gpgsign true

To also always sign your tags:

git config --global tag.gpgsign true

Configure GitHub

To have commits marked as signed in GitHub, you have to add SSH key one more time, and choose it to be your Signing Key:

Add new SSH signing key in GitHub

After doing that, your signed commits will be marked as Verified:

Commit signed with SSH key as displayed in GitHub

Local signers file

You can also create an allowed signers file for quick local verification of signatures

Create a file (e.g., ~/.config/git/allowed_signers) listing trusted email and public key pairs in this format:

your.email@example.com ssh-ed25519 AAAAC3NzaC1...

Then tell Git to use it:

git config --global gpg.ssh.allowedSignersFile '~/.config/git/allowed_signers'

You can now verify if your commit was signed properly:

$ git verify-commit <hash>
Good "git" signature for your.email@example.com with ED25519 key SHA256:<...snip...>

You can do it for git log as well:

$ git log --show-signature
commit <hash> (HEAD -> main, origin/main)
Good "git" signature for your.email@example.com with ED25519 key SHA256:<...snip...>
Author: John Doe <your.email@example.com>
Date:   Fri May 30 21:22:36 2025 +0200

    Hello there

Further reading

  1. I don’t want to go into details, but e.g. this blog post does it very well ↩
  2. If you don’t have your SSH key set up, this blog post will be helpful. They go into much more details along with tips how to load SSH keys into keychain on MacOS etc. ↩
  3. This video shows different ways to sign a Git commit. Also, author states that he doesn’t sign his commits, so you clearly see that opinions vary on this topic. ↩
✵