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. When a project checkout 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, not a task worktree. It sets commit.gpgsign true for the checkout and false for its task worktrees (which would otherwise try to sign on the server and fail), prints both values, and fails unless the checkout's reads true. It refuses a checkout that is itself a linked worktree. 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.