Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Git: gpg failed to sign the data, and why the commit is not written

No commit is created when signing fails. List the secret keys, expose a TTY, and point Git at the right gpg binary.

~5 min readGit
#Git#GPG#Commit Signing#Security
A commit slab with a broken amber signature seal beside a key ring and a cyan terminal plate

Introduction & Quick Summary

git commit fails with error: gpg failed to sign the data followed by fatal: failed to write commit object. The commit is not created at all, and git log still shows the previous HEAD. Nothing is corrupted; signing happens before the object is written.

Git is trying to make a detached signature and the gpg process it spawned either could not find a usable secret key, could not ask for the passphrase, or was pointed at the wrong program. The four causes that account for nearly every report:

  1. No signing key configured, or the configured key is not in the keyring - user.signingkey unset, or set to an ID that was never imported on this machine.
  2. No terminal for the passphrase prompt - GPG_TTY is unset, so pinentry cannot ask, which is the classic failure inside VS Code, JetBrains, a GUI git client, or a git commit run from a hook.
  3. The wrong gpg binary - on Windows and in some Nix/macOS setups, git finds gpg while the keyring lives under gpg2, or the reverse.
  4. An expired or revoked key - the signature cannot be produced, and the error is the same sentence.

The fastest check is two commands: list the secret keys, then ask gpg to sign a string by hand. If the second fails, Git is not the problem.

Core Mechanics, Signatures & Reproducible Setup

With commit.gpgSign=true or -S, Git builds the commit object, pipes it to gpg --status-fd=2 -bsau <key>, and embeds the armored signature in the commit header. Any non-zero exit aborts the commit with the message above; the --status-fd output that explains why usually goes to stderr but is often swallowed by editors and IDE git panels.

bash
# what is Git told to do git config --get commit.gpgsign git config --get user.signingkey git config --get gpg.program # what gpg can actually see gpg --list-secret-keys --keyid-format=long gpg --list-secret-keys --keyid-format=long | grep -E '^(sec|uid)' # the decisive test: sign without Git involved echo "test" | gpg --clearsign >/dev/null && echo "gpg can sign" || echo "gpg cannot sign"

Reproduce the failure deterministically by pointing Git at a key that does not exist:

bash
git config user.signingkey DEADBEEFDEADBEEF git commit -S -m "probe" # gpg: skipped "DEADBEEFDEADBEEF": No secret key # error: gpg failed to sign the data

Run the same commit with tracing to see the exact gpg invocation, which distinguishes a key problem from a pinentry problem:

bash
GIT_TRACE=1 git commit -S -m "probe" 2>&1 | grep -A2 'gpg'

Key Comparison Table

Failure stageMessage or symptomCauseFix
Key lookupNo secret keysigningkey wrong or not importedset the long key ID from --list-secret-keys
PassphraseInappropriate ioctl for deviceno TTY for pinentryexport GPG_TTY and use pinentry-curses
Programgpg: command not foundgpg not on PATH for the GUI appset gpg.program to the absolute path
Key stateKey expired or revokedold key still configuredextend the expiry or rotate
Agentgpg-agent not runningagent socket stale after suspendgpgconf --kill gpg-agent
Signature formatunknown value for gpg.formatssh signing with a gpg key pathalign key and format
ApproachKey materialSetupNotes
GPG signinggpg keyringkeyring plus agentworks everywhere, needs pinentry
SSH signingssh keyone config plus an allowed-signers fileno agent prompt issues, GitHub supported
Commit template with -Sanynonesigns only when asked
commit.gpgsign=true globallyanynoneevery commit, including rebases

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. gpg failed to sign inside an editor or IDE

The commit works in a terminal and fails from VS Code's source control panel. The GUI process has no controlling terminal, so pinentry falls back to a graphical program that is not installed. Expose the terminal and tell pinentry to use the curses interface on the command line:

bash
# ~/.zshrc or ~/.bashrc export GPG_TTY=$(tty) # ~/.gnupg/gpg-agent.conf # pinentry-program /usr/bin/pinentry-curses

After editing the agent config, reload it with gpgconf --kill gpg-agent; the next signature starts a fresh agent that reads the new setting.

2. The configured key ID is truncated or wrong

gpg --list-keys prints short IDs that collide, and copying a fingerprint from a web page often drops a character. Use the long ID or the full fingerprint, and confirm it maps to the identity you expect:

bash
gpg --list-secret-keys --keyid-format=long # sec rsa4096/4C2B1F8A9D3E77C1 2024-03-02 [SC] [expires: 2027-03-02] # 8F2A13C4B9E05D6A7C1B4C2B1F8A9D3E77C1 git config --global user.signingkey 4C2B1F8A9D3E77C1 git config --global user.email "you@example.com" # must match the key's uid

A key whose UID email differs from user.email still signs, but verifiers show an unverified commit, which looks like a signing failure in review.

3. Windows: two gpg installations, one keyring

Git for Windows ships gpg.exe, and Gpg4win installs another with its own keyring path. The key generated in Kleopatra is invisible to Git's copy. Point Git explicitly at the binary that owns the keys:

bash
git config --global gpg.program "C:/Program Files (x86)/GnuPG/bin/gpg.exe" where gpg gpg --list-secret-keys --keyid-format=long

If both must exist, export the key from one and import it into the other rather than switching programs per repository.

4. Moving to SSH signing removes the agent problem

If the only goal is verified commits on a hosting provider, SSH keys sign without pinentry and without a keyring daemon:

bash
git config --global gpg.format ssh git config --global user.signingkey ~/.ssh/id_ed25519.pub git config --global commit.gpgsign true # local verification needs an allowed signers file echo "$(git config user.email) $(cat ~/.ssh/id_ed25519.pub)" > ~/.ssh/allowed_signers git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers

The public key must be registered with the hosting provider as a signing key, not only as an authentication key; the two registrations are separate.

5. Rebases, amends and automated commits

commit.gpgsign=true covers git commit, --amend, git rebase and git cherry-pick, so a key that expires mid-history breaks automation that previously worked. Keep a signing-only identity for bots and make the requirement explicit:

bash
gpg --quick-set-expire 4C2B1F8A9D3E77C1 2y git -c commit.gpgsign=false commit -m "chore: no signature in this sandbox"

The per-command override is honest for a throwaway container; disabling it globally to get CI moving is how unsigned commits reach a repository that requires them.

6. Verifying that the result is what you think

After a fix, confirm the commit is signed and that the signature verifies locally, not only that the command stopped failing:

bash
git log -1 --show-signature git verify-commit HEAD

A commit can carry a signature that does not verify (expired key at verification time, wrong subkey). --show-signature shows the reason inline; for a busy history, pipe the output of git log --show-signature through a search with Text Diff when comparing two branches, which makes the unsigned commit visible in the alignment.

Common Compilation/Runtime Mistakes & Version Gotchas

  • git config --global commit.gpgsign true before a key exists. Every commit on that machine, including in unrelated repositories, now fails.
  • Setting user.signingkey to the public key file path. That is the SSH signing form; with gpg.format=openpgp Git passes the path to gpg, which cannot use it.
  • Assuming the pinentry fix needs a GUI package. pinentry-curses works over SSH and in containers; installing a full desktop pinentry on a server is unnecessary.
  • Forgetting gpgconf --kill gpg-agent. Config changes to gpg-agent.conf do nothing until the running agent is replaced.
  • GPG 2.1+ keyring migration. Keys generated under GnuPG 1.x are not visible to 2.1+ until imported into the new keyring; --list-secret-keys empty on a machine that used to sign is this, not a lost key.
  • git rebase -i with -S. Signing the rewritten commits requires the agent to stay unlocked for the whole rebase; a locked key stops halfway with the same error.
  • Container images without gnupg. A CI image built on alpine or debian-slim may lack gpg entirely, and the error text does not say the binary is missing. GIT_TRACE=1 shows gpg: not found.

Primary references: the commit.gpgSign configuration in git-config documents the signing behaviour and the per-command override, and GitHub's telling Git about your signing key covers the key registration that verification depends on.

Official references

primary documentation

The Git documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Git guides

More in Git

All Git guides

The guides filed next to this one in Git, in library order.