git commit 'error: gpg failed to sign the data' / 'fatal: failed to write commit object'. How do I fix GPG commit signing?

Cause: Git calls gpg to sign the commit and gpg failed. Usual reasons: gpg cannot ask for your passphrase because there is no TTY (GPG_TTY unset) or the agent/pinentry is not working; user.signingkey names a key that does not exist or has no secret part; the key expired; git is calling a different gpg program than the one holding your keys; or the gpg-agent is stuck. Fix: 1. Check the key: gpg --list-secret-keys --keyid-format=long. Only keys with a secret part can sign; make sure it is not expired. 2. Point Git at it: git config --global user.signingkey <LONG-KEY-ID>. With several keys on one account, GitHub's docs note you can append ! to select a specific one. 3. Give gpg a terminal for the passphrase prompt: add export GPG_TTY=$(tty) to your shell startup file (.bashrc, .zshrc) and restart the shell. 4. Use the right program: some Linux installs need git config --global gpg.program gpg2 (or the full path to the gpg that holds your keys). On macOS install a pinentry such as pinentry-mac and reference it in gpg-agent.conf. 5. Restart the agent if it hangs: gpgconf --kill gpg-agent and retry. 6. Test gpg alone: echo test | gpg --clearsign. If that fails, fix gpg first; the error is not a Git problem. 7. If you set commit.gpgsign true and just need to commit once while debugging, use git commit --no-gpg-sign, but fix signing afterwards if your project requires signed commits. Verify: git commit -S -m "test" succeeds and git log --show-signature -1 shows a good signature. Sources: https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key https://git-scm.com/docs/git-config