how to require signed commits on a repo

how to require signed commits on a repo

TL;DR

Turn on "require signed commits" in the repo's branch protection rules for your main branches, and have every contributor sign with GPG or SSH keys registered on their GitHub account. GitHub then rejects unsigned pushes to those branches. Also enable vigilant mode so your own commits show as verified, which makes impersonation attempts visible.

The query

how to require signed commits on a repo

Use this when

• you want cryptographic proof that commits came from the claimed author
• someone asks "how do I enforce signed commits" or "why is my push rejected as unsigned"
• you are setting up branch protection for a production repo
• you are responding to a commit-impersonation scare

Not for this skill when

• you only need review approvals (signed commits and required reviews are separate rules, use both)
• you are signing release artifacts (that is a different workflow from commit signing)
• contributors cant install signing tools (fix onboarding before enforcing)

Steps

1. Generate a signing key: ssh-keygen -t ed25519 -f ~/.ssh/id_signing works for SSH signing, or create a GPG key if your org standardized on GPG.

Expected output: the key files exist and listing keys shows the new key.

1. Tell git to sign: git config --global commit.gpgsign true, plus git config --global gpg.format ssh and git config --global user.signingkey ~/.ssh/id_signing.pub for SSH signing.

Expected output: git config --list shows commit.gpgsign true and the signing key path.

1. Register the public key on GitHub under Settings, SSH and GPG keys, as a signing key.

Expected output: GitHub lists the key with type Signing Key.

1. Make a test commit and push, then check the commit on GitHub.

Expected output: the commit shows a Verified badge.

1. Enforce it: in repo Settings, Branches, add a rule for main (and release/* if you have them) with "Require signed commits" checked.

Expected output: pushing an unsigned commit to main is rejected with a rule-violation message.

1. Turn on vigilant mode in your GitHub settings so commits you did not sign show as Unverified on your profile.

Expected output: any impersonation attempt is visibly flagged.

Variant: GPG instead of SSH

Set gpg.format to openpgp (the default), generate with gpg --full-generate-key, and register the GPG public key. The GitHub UI flow is the same.

Variant: existing unsigned history

Enforcement only applies to new pushes. Old history stays unsigned, which is fine; note the cutoff date in your security docs.

Variant: bots and automation

Give CI bots their own signing keys and register them, or exempt the bot's branch pattern with a narrower rule. Dont share one key across humans and bots.

Why this happens

Git lets anyone set any author name and email on a commit, so "authored by the CTO" proves nothing by itself. Signing binds each commit to a private key only the author holds, and branch protection makes the signature mandatory rather than advisory.

Edge cases and pitfalls

• Rebases and web UI merges can drop signatures. Require linear history or squash merges with signing-aware settings, and test your actual merge flow.
• Lost keys mean the contributor must generate a new one and re-register; there is no recovery, so document the rotation steps.
• Some git clients and IDEs ignore commit.gpgsign. Verify with a real push, not just the config file.
• Enforcement blocks hotfix pushes from machines without keys. Keep a documented break-glass process with post-incident review.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstgrELTDiwoGQtGDf9V1zbQ