SSH Commit Signing — Setup Notes
Why
The infrastructure GitHub repo enforces an org-wide ruleset called "Signed commits in all branches" (required_signatures, scope: all refs, no bypass for anyone — including admins). Unsigned commits/pushes will be rejected on any branch.
GitHub's required_signatures rule accepts GPG, SSH, or S/MIME signatures interchangeably — it just checks for a verified signature, not a specific type. SSH is the simplest option since most devs already have an SSH key for GitHub auth (though GitHub treats "Authentication Key" and "Signing Key" as separate key roles — you must add your key as a signing key, even if it's already registered as an auth key).
1. Get or generate an SSH key
Reuse your existing GitHub auth key, or generate a dedicated signing key:
# check for an existing key
ls -la ~/.ssh/id_ed25519.pub
# or generate a new one (ed25519 recommended)
ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/id_ed25519_signing
2. Tell Git to use SSH for signing
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true
Optional — sign tags too:
git config --global tag.gpgsign true
3. Register the key with GitHub as a signing key
- Copy the public key:
cat ~/.ssh/id_ed25519.pub - GitHub → Settings → SSH and GPG keys → New SSH key
- Key type:
Signing Key(not "Authentication Key" — a key can be added twice, once for each role, if you want to reuse the same key)
4. (Optional but recommended) Verify signatures locally
Create an allowed-signers file so git log --show-signature and local verification work, not just GitHub's UI:
echo "your_email@example.com $(cat ~/.ssh/id_ed25519.pub)" >> ~/.ssh/allowed_signers
git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers
5. Verify it works
git commit --allow-empty -m "test: verify SSH commit signing"
git log --show-signature -1
Push the commit and check GitHub shows a "Verified" badge on it.
Notes
commit.gpgsign truesigns every commit automatically — no need to pass-Seach time.- If you use multiple machines, each needs its own key added to GitHub as a signing key (or copy the same private key, less ideal).
- If a commit shows "Unverified" on GitHub after this, the most common cause is the key being registered as Authentication only, or the git author email not matching a verified email on your GitHub account.
