Git Reference ยท Configuration Options
gpg.* settings
Reference for gpg.* settings: gpg.format (openpgp, x509, ssh), gpg.program, gpg.ssh.allowedSignersFile and gpg.minTrustLevel for signed commits and tags.
The gpg.* settings tell Git how to create and check signatures on commits, tags and pushes. Despite the name they cover three signature formats: OpenPGP (the original, through the gpg program), X.509 (S/MIME, through gpgsm) and SSH (through ssh-keygen). Which key signs is chosen by user.signingKey; whether signing happens automatically is decided by commit.gpgSign and tag.gpgSign.
git config --global gpg.format ssh git config --global user.signingKey ~/.ssh/id_ed25519.pub git config --global gpg.ssh.allowedSignersFile ~/.config/git/allowed_signers git config --global commit.gpgSign true
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
git config gpg.format (openpgp | x509 | ssh) git config gpg.program <program> git config gpg.<format>.program <program> git config gpg.minTrustLevel (undefined | never | marginal | fully | ultimate) git config gpg.ssh.allowedSignersFile <path> git config gpg.ssh.defaultKeyCommand <command> git config gpg.ssh.revocationFile <path>
| Name | Description |
|---|---|
gpg.format |
Signature format used when creating signatures. Default openpgp. Verification detects the format from the signature itself. |
gpg.program |
Legacy name for the OpenPGP program (default gpg). Still honored. |
gpg.openpgp.program, gpg.x509.program, gpg.ssh.program |
Program for each format: gpg, gpgsm, ssh-keygen. |
gpg.minTrustLevel |
Verification of a signature counts as failed if the signer's key trust is below this level (OpenPGP and X.509). |
gpg.ssh.allowedSignersFile |
File listing principals and public keys allowed to sign; required to verify SSH signatures. |
gpg.ssh.defaultKeyCommand |
Command that prints the key to use when user.signingKey is not set (for example ssh-add -L). |
gpg.ssh.revocationFile |
File of revoked keys checked during verification. |
Errors: if the signing program is missing or fails, the commit stops with error: gpg failed to sign the data and fatal: failed to write commit object. Verifying an SSH signature without an allowed-signers file reports that the file is not configured.
Usage notes
- Three separate questions: which format (
gpg.format), which key (user.signingKey), and whether to sign automatically (commit.gpgSign,tag.gpgSign,push.gpgSign). Missing any one causes confusion. - SSH signing needs Git 2.34 or later and OpenSSH 8.0+ on the machine. For a key stored in an agent, set
user.signingKeyto the public key text prefixed withkey::or to a.pubfile path. - The allowed-signers format is one line per signer: principals (usually an email), optional options, then the key type and key. Git matches the committer email against the principal.
- Verify with
git log --show-signature,git verify-commitorgit verify-tag; seelog.*for thelog.showSignatureshortcut. - A good signature is not trust. It only proves the holder of the key made the commit; deciding whether to trust that key is up to you (
gpg.minTrustLevel, allowed signers, key servers). - GitHub and GitLab show a "Verified" badge when the public key was uploaded to the account and the signature matches the committer email.
- Rewriting history removes signatures. Rebasing or amending creates new commits; with
commit.gpgSign=truethey are signed again with your current key.
Related
commit.*,git tag,user.*- Lessons: Signing and security, Supply-chain security