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.
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
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.
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 --amendandcherry-pickcreate new commits that are unsigned unless you pass-Sor enablecommit.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.