Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
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

Bash Signing through a stand-in program

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.

Bash Reading and combining the settings

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

Terminal
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.signingKey to the public key text prefixed with key:: or to a .pub file 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-commit or git verify-tag; see log.* for the log.showSignature shortcut.
  • 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=true they are signed again with your current key.