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

1. Copy the public key: cat ~/.ssh/id_ed25519.pub
2. GitHub → Settings → SSH and GPG keys → New SSH key
3. 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 true signs every commit automatically — no need to pass -S each 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.