Commit signing

Three kinds of commit come out of the factory, and each is signed differently:

Who commits	Signed by	GitHub shows
You, from a factory page (the conflict editor, a resolution you commit by hand)	Your own key, held in AWS KMS	Verified, as you
An agent in a Pix Sandbox	Pix’s sandbox key, as Pix [bot]	Verified, as Pix [bot]
The Vulnetix GitHub App on its own	GitHub, as the App	Verified, as the App

Agents never use a person’s key.

Your signing key

Each GitHub user in your organisation has at most one key. It is a Secrets Vault entry with no value: the private half is made inside AWS KMS (ECDSA P-256) and can never be exported. Only the person signed in as that GitHub user can create or use it. Admins can see its state and revoke it, but never create one or sign with it.

State	Meaning	You can
ready	In the vault and listed on GitHub	Rotate, revoke
not_on_github	Someone removed it from GitHub	Add it again
no_permission	The GitHub App cannot add keys to your account	Grant permission, or copy the public key and add it by hand
revoked	Disabled and scheduled for deletion	Nothing

With no key, the state is not_set_up.

Commits as

Beside every button that commits as you, a control says how the commit will be made:

Shows	Means
✓ as @you · signed	Ready
○ as @you · no signing key	Set one up first
! as @you · key not on GitHub	Add it again
! as @you · App cannot add keys	Grant the App permission
✕ branch requires signed commits	The branch needs a signed commit and you have no key
◇ GitHub signs this	GitHub makes and signs the commit itself, for example Update branch

Settings

Settings › Commit signing:

Setting	Values	Default	Effect
signing.mode	required, preferred, off	preferred	Whether a commit from a factory page must be signed
signing.auto_add	on, off	on	Add a new key’s public half to the person’s GitHub account
signing.email	primary, noreply, ask	primary	The address on the commit
signing.on_missing	readd, ask	readd	What to do when GitHub no longer lists a key
signing.rotate_days	365, 180, 90, 0 (never)	365	How often a key is replaced
signing.retire_days	30, 7, 0 (right away), -1 (leave it)	30	How long a replaced key stays on GitHub, so older commits stay Verified

A signing key that drops off GitHub shows in the cockpit’s Needs you list.

API

Method	Path
GET	/v1/signing/keys
POST	/v1/signing/keys (create yours)
POST	/v1/signing/keys/{id}/github (add to GitHub again), /check, /rotate
DELETE	/v1/signing/keys/{id} (revoke)
GET	/v1/signing/state?owner=&name=&branch= (what “Commits as” shows)
GET	/v1/signing/github/authorize, /v1/signing/github/callback (grant the App permission to add keys)

Related

• Merge conflicts for the conflict editor.
• Pix Sandboxes for agent signing.