byre/internal/agents/kb/signing.md

How byre signs merge commits on the merging user's Mac, and how to turn it on for a project.

Signing merge commits

byre never signs with a key on the machine it runs on: its own end-of-turn and snapshot commits there are always unsigned. When a project checkout (or the server's global config) has commit.gpgsign true, the squash commit of a Merge or merge_to_main is signed on the merging user's most recently active connected Mac, so a key that never leaves that Mac (a Secure Enclave key behind Touch ID, say) works. The merge fails when that user has no app connected.

Turning it on

Run, on the machine byre runs on:

byre signing <checkout>

<checkout> is the project's main checkout. It sets commit.gpgsign true for the checkout, prints it, and fails unless it reads true. No restart is needed; the next merge reads the config.

What the Mac needs

The Mac's own git signing config, the same that signs the user's local commits:

• gpg.format: openpgp (default) or x509. ssh is not supported.
• The program, when it isn't gpg or gpgsm: gpg.openpgp.program or gpg.program, or gpg.x509.program.
• user.signingkey, when the program can't find the key from the user's git identity in byre.

The program must print [GNUPG:] SIG_CREATED on its status fd. A Touch ID prompt left unanswered for 2 minutes fails the merge.

Checking

git -C <checkout> cat-file commit HEAD shows a gpgsig header on a signed merge commit. The notes commit under refs/notes/byre is not signed.