Qvantor logo QvantorInfrastructure, explained plainly
Dev Tools

Sign Git Commits With an SSH Key in Fifteen Minutes

Anyone can set their Git name and email to yours. It takes one line of config, no password and no access to your accounts, and the resulting commit shows up in history looking exactly like your work.

A laptop terminal showing a git log entry with a good signature line beside a small hardware security key

Anyone can set their Git name and email to yours. It takes one line of config, no password and no access to your accounts, and the resulting commit shows up in history looking exactly like your work. On a small team that pushes straight to a shared repository, nobody would notice until something went wrong and the blame pointed at the wrong person.

Signing commits closes that gap. For years the only practical way was GPG, and most developers I know tried it once, lost an afternoon to expired subkeys and agent errors, and gave up. Since Git 2.34 you can sign with the SSH key you already use to push, and the setup fits in about fifteen minutes. This is the version I walk teams through.

What a signature proves, and what it does not

A signed commit carries a cryptographic signature made with a private key. Anyone holding the matching public key can check two things: the commit content has not changed since it was signed, and the signer held that private key at the time.

That is all. A signature does not prove the code is safe, that it was reviewed, or that the person typing was the person who owns the laptop. If your key sits unencrypted on a machine that gets stolen, the thief signs as you. So the value of signing depends heavily on how you protect the key, which is why I spend more time on that below than on the Git config itself.

It also does not stop someone from pushing an unsigned commit with your name on it. It only makes that commit look different. The protection comes from a host or a review habit that treats unsigned commits as suspicious, and we will set that up too.

Setting up SSH commit signing

You need Git 2.34 or newer. Check with git version. Ubuntu 22.04 ships 2.34.1, macOS with Homebrew is usually far ahead, and Git for Windows has supported it since late 2021.

If you followed our walkthrough on SSH key authentication for a small Linux server, you already have an ed25519 key pair. You can reuse it, but I prefer a separate signing key, for a reason I explain in the next section. Generating one takes ten seconds with ssh-keygen and the ed25519 type, saved to something like id_ed25519_signing.

Then the config, run inside a repository. Add the global flag to each line if you want it everywhere:

  1. git config gpg.format ssh, which tells Git to use SSH instead of GPG for every signature.
  2. git config user.signingkey followed by the path to your public key file, for example ~/.ssh/id_ed25519_signing.pub.
  3. git config commit.gpgsign true, so every commit is signed without you remembering a flag.
  4. git config tag.gpgsign true, so release tags get the same treatment.
  5. Make a test commit, then run git log with the show-signature option to see the result.

The setting names still say gpg for historical reasons. That confuses almost everyone the first time. It does not mean GPG is involved.

At step five you will probably see an error saying gpg.ssh.allowedSignersFile needs to be configured. That is expected. Git can sign, but it does not yet know whose keys to trust when verifying, and that is the next piece.

The allowed signers file

Verification locally runs through a plain text file, one line per person: an email address, a space, then the full public key line. I keep it in the repository itself at .github/allowed_signers or a similar path, so it is reviewed like any other change, and point Git at it with git config gpg.ssh.allowedSignersFile followed by that path.

Now git log with show-signature prints Good git signature for your email with the key fingerprint. When a teammate joins, they open a pull request adding their line. When someone leaves, their line is removed in the same pull request that revokes their access, which ties nicely into an offboarding checklist you probably already run.

Telling the hosting service

GitHub, GitLab and Gitea each let you upload a public key specifically as a signing key, separate from authentication keys. On GitHub it sits in the same SSH keys page, with a key type dropdown that defaults to authentication. Upload the signing key with the type set to signing, and your commits start showing a Verified badge. If you skip this, the commits are still signed, but the web interface marks them Unverified, which teaches everyone to ignore the badge.

Why reusing your login key is the wrong default

A lot of guides say to point user.signingkey at the key you already push with. It works, and it saves a step. I think it is the wrong habit for anyone beyond a solo hobby project.

Your authentication key tends to live everywhere. It sits in an agent that forwards to servers, it gets copied to a second laptop, and sometimes it has no passphrase because typing one on every push got annoying. All of that is tolerable for a key whose worst case is someone pushing to your repo, since the host logs it and you can revoke it.

A signing key has a different job. Its whole point is to be hard to use by anyone but you. If it never leaves one machine, has a passphrase, and is never forwarded, a signature actually means something. Mixing the two roles means either your login key gets annoyingly strict or your signing key gets dangerously loose. Two keys cost nothing.

The strongest option is a hardware key. A YubiKey 5 at around 55 dollars can hold an ed25519-sk key, generated with the ed25519-sk type in ssh-keygen. Every signature then needs a physical touch. I use this for release tags only, because touching a key on every commit during a rebase of thirty commits wears thin fast. Our piece on hardware security keys for a small team covers buying and enrolling them.

Where signing gets annoying

Rebases re-sign every commit, because rewriting a commit creates a new one. With a passphrase on the key and no agent running, an interactive rebase of 20 commits asks 20 times. Load the key into ssh-agent once per session and the prompts disappear.

Squash merges done through the web interface are signed by the host, not by you. GitHub signs them with its own key, so they show as Verified even though you never touched them. That is fine, but it means a Verified badge on main does not always mean a person signed it.

Old commits stay unsigned. Do not rewrite history to sign them. Pick a date, announce that everything after it should be signed, and leave the past alone.

CI systems that create commits, such as release bots bumping a version number, need their own signing key, stored as a secret and listed in the allowed signers file under a bot address. Otherwise the first automated commit after you turn on enforcement fails, usually at 2am.

Turning it into a rule

Signing that nobody checks is decoration. Once everyone on the team has signed for about two weeks without trouble, turn on the branch protection setting that requires signed commits on main. On GitHub it is called Require signed commits. GitLab offers a similar push rule on its paid tiers, and on the free tier you can approximate it with a CI job that runs git verify-commit across the commits in each merge request.

In my experience with four small teams, the rollout goes smoothly when one person sets it up, writes a half page for the wiki with the exact commands for macOS, Linux and Windows, and sits with each colleague for ten minutes. It goes badly when the rule is switched on first and everyone discovers it through a rejected push on a Friday.

FAQ

Do I need GPG installed to sign Git commits with SSH?

No. With gpg.format set to ssh, Git calls ssh-keygen to sign and verify. GPG can be absent entirely.

Can I use the same SSH signing key on two laptops?

You can, but I would generate one key per machine and add both lines to the allowed signers file. If one laptop is lost, you remove one line instead of replacing the key everywhere.

Why do my signed commits show Unverified on GitHub?

Usually the key was uploaded as an authentication key rather than a signing key, or the email in the commit does not match a verified email on your account. Check both.

Does signing slow down committing?

With the key loaded in an agent, the delay is a few milliseconds. With a hardware key it is the second or so it takes to touch it.

ON
Obi Nwachukwu

Obi works on account security and explains phishing, passwords and access in plain terms.

More posts by Obi

More in Dev Tools

01doorganico 084goad 3hot8 4465456 after5internprogram ahandfulofblessings ahmadpc ahomcybersecurity allodialresources annodex antiquesandperiodcollectibles aotc asianworldkashmir beedlectrics bloggertemplatefree bluefeatheragency bodyweightsolution campaign08blog carfixadvisor catstreetcollective cbstvsports cnfanspurchasing committeeof500yearsofdignityandresistance covertopsdjs cs-kaiyuangame cuestacomunicaciontotal cxoutlet dancebetgame deskgearhub destinyvillastay detectmagazine di33 diamondsteelbuildings donmo dyanadropship emarsysfinance emimattl escapechan eskitarih evautoplay everythingweddings-orlando farmzone feedviewerapp foxstudiosscratch gamevui123 gleasongrade greetingsday hacklabasu haskell iw-kaiyun jagoanproperti jilidskripsi joltbusinessfinance juegodepokergratis juegospucca kaeru-festival latestmehndidesigns lestanzediottaviano litemagazines localcommunityhero lustrsazan mariashebets menswheels newwebstechs1 nikkit ootheday oxigenvpn plurfitness prefetial probudgetcarpetcleaning psychicmrsmartin pyaten rejoignezlogis rexzbot riselayouts ruchin rwxqsgd5 sakaltime shibiaowang shop-bot skrtips spotlesshaven strcoding tetapatrium topselller uneplanteartificielle vipertechcr webtech1223411 wo-kygaming yamaha-mekar yeknava yoybuysheets zenunwa yamaha-mekar jilidskripsi ankertoto ankertoto ankertoto