Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Objects, Refs and Internals

Signed commits and tags

Reference for signed commits and tags: where the gpgsig header and tag signature live, the three formats (OpenPGP, SSH, X.509), verification and trust settings.

A signature lets someone prove that a commit or tag was created by the holder of a private key. Git does not invent its own cryptography: it hands the object text to an external program (GnuPG, ssh-keygen or gpgsm), stores the resulting signature inside the object, and later passes the object and signature back for verification.

Signing changes the commit's ID like any other content, so you cannot sign a commit after the fact without rewriting it (and its descendants). What the signature covers is the whole commit text: tree, parents, author, committer, message. Anyone who can alter the history of an unsigned branch can change it; with signatures, they cannot forge new commits in your name.

Terminal
git commit -S -m "message"        # sign this commit
git tag -s v1.0 -m "release"      # sign an annotated tag
git verify-commit HEAD            # check a commit signature
git log --show-signature          # show verification in the log

Try it

Bash Sign a commit with a throwaway GPG key

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 Signed tags carry the signature in the message

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.

Where the signature is stored

Object Location of the signature
Commit A gpgsig header after committer (and encoding). The signature's lines are continued with a leading space, and a blank line inside the block is written as a single space. In a repository that keeps both SHA-1 and SHA-256 names, a gpgsig-sha256 header may appear next to it.
Annotated tag Appended to the end of the tag message, after the text. It is not a header.
Push certificate Sent to the server by git push --signed; it signs the ref updates rather than an object, and the server needs receive.certNonceSeed to accept it.

The text that gets signed is the object without the signature itself. For a commit, Git removes the gpgsig header, signs the remaining text, then inserts the header. Verification does the reverse. For a tag, the signature covers all headers and message text before the signature block.

Signature formats

gpg.format chooses the format:

Value Program Signature looks like Key setting
openpgp (default) gpg (gpg.program) -----BEGIN PGP SIGNATURE----- user.signingkey is a key ID or e-mail.
ssh ssh-keygen (gpg.ssh.program) -----BEGIN SSH SIGNATURE----- user.signingkey is a public key or key::... string. Verification needs an allowed signers file (gpg.ssh.allowedSignersFile). Supported since Git 2.34.
x509 gpgsm (gpg.x509.program) -----BEGIN SIGNED MESSAGE----- Certificates and a trust chain.

Setting commit.gpgSign=true or tag.gpgSign=true signs by default, and --no-gpg-sign overrides it for one command.

Verification status

git log --format=%G? prints one letter per commit:

Letter Meaning
G Good signature.
B Bad signature.
U Good signature, validity unknown (key not trusted).
X Good, but the signature has expired.
Y Good, but made by an expired key.
R Good, but made by a revoked key.
E Cannot be checked, for example because the key is missing.
N No signature.

%GS is the signer, %GK the key, %GF the fingerprint, %GT the trust level. merge.verifySignatures makes git merge refuse unsigned or untrusted commits, and git verify-commit/git verify-tag return a non-zero exit code on failure.

Usage notes

  • Rewriting drops signatures. rebase, commit --amend and cherry-pick create new commits that are unsigned unless you pass -S or enable commit.gpgSign.
  • Squash merges on hosting sites are signed by the platform's key, not yours.
  • Expiry and revocation are judged when you verify, by your local keyring; Git stores the signature, not trust.
  • Hosting display. "Verified" badges on GitHub or GitLab need the public key uploaded to your account.
  • Private keys never enter the repository. Only the signature and, for SSH, nothing else is stored. Publish the public key separately.