Skip to content

Signed commits ​

main in home-dashboard and lovely-hub-provision is meant to require signed commits (#1205). Every commit on main then shows Verified and names who made it.

Who signs what ​

CommitSigned by
Your commits from a laptopYour GPG key (set up once per machine, below)
Claude cloud sessionsThe session's own SSH signing key, already on
PR merges, squashes and rebases (button, API, auto-merge)GitHub
Site registry platform: record/drop … commitsGitHub, through createCommitOnBranch
sync-public-* workflow syncs to lovely-hub-provisionGitHub, through createCommitOnBranch

Bot jobs that write to main must use scripts/lib/github-signed-commit.mjs, never git commit + git push. A commit made through GitHub's API is signed by GitHub and credited to the token's owner.

Bot commits that only go to their own branch (hub visual baselines, marketing screenshots, platform site PRs, registry snapshot branches) stay unsigned. Their PRs must be squash merged: GitHub signs the squash, while a normal merge would copy the unsigned commits onto main and be refused.

Set up a GPG key ​

  1. Install GPG (brew install gnupg pinentry-mac on a Mac).
  2. gpg --expert --full-generate-key (GPG 2.2 hides ECC without --expert): (10) ECC (sign only), (1) Curve 25519, 2 year expiry, your GitHub email. Fallback: (4) RSA (sign only), 4096 bits.
  3. gpg --list-secret-keys --keyid-format=long and copy the ID after ed25519/.
  4. gpg --armor --export {ID} and paste it into GitHub → Settings → SSH and GPG keys → New GPG key.
  5. git config --global user.signingkey {ID}, git config --global commit.gpgsign true, git config --global tag.gpgsign true.
  6. Mac: echo "pinentry-program $(brew --prefix)/bin/pinentry-mac" >> ~/.gnupg/gpg-agent.conf && gpgconf --kill gpg-agent. Elsewhere: export GPG_TTY=$(tty) in your shell profile.
  7. Check with git log --show-signature -1 after a commit.

Enforcing it ​

  • home-dashboard (private, personal account): GitHub does not enforce rulesets or branch protection here without a paid organisation. The Signed commits check (signed-commits.yml, scripts/check-signed-commits.mjs) does it instead: it fails a PR with an unsigned commit (a bot's unsigned commit only warns, because those PRs are squash merged) and fails, with a Slack alert, if an unsigned commit lands on main. PRs merge only when CI is green. The classic rule on main with Require signed commits stays in place and starts enforcing if the repo ever moves to a paid plan.
  • lovely-hub-provision (public): Settings → Rules → Rulesets → New branch ruleset, target the default branch, tick Require signed commits, enforcement Active, no bypass.

To check that GitHub signs API commits for a token, make a createCommitOnBranch commit on a throwaway branch and read gh api repos/{repo}/commits/{branch} --jq .commit.verification.