How to fix error: gpg failed to sign the data error: unable to sign the tag in Git

The most common fix is to set the GPG_TTY variable so GPG knows which terminal to use for passphrase entry:

export GPG_TTY=$(tty)

Add this to your shell configuration file for persistence:

# For bash
echo 'export GPG_TTY=$(tty)' >> ~/.bashrc

# For zsh
echo 'export GPG_TTY=$(tty)' >> ~/.zshrc

Then reload your shell configuration:

source ~/.bashrc  # or ~/.zshrc

Before troubleshooting Git, verify that GPG itself can sign data:

echo "test" | gpg --clearsign

If this command:
- Works and shows signed output: GPG is functioning; the issue is Git configuration
- Hangs: The pinentry program cannot display a prompt
- Shows "no default secret key": No signing key is configured
- Shows "unusable secret key": The key may be expired or corrupted

List your GPG keys and check their expiration dates:

gpg --list-keys --keyid-format LONG

Look for [expired] next to your key. If expired, extend the expiration date:

gpg --edit-key YOUR_KEY_ID
gpg> expire
# Follow prompts to set a new expiration date
gpg> save

After extending, you may need to re-upload your public key to GitHub/GitLab.

Ensure Git is configured to use the correct GPG program and signing key:

# Check current configuration
git config --global user.signingkey
git config --global gpg.program

# List available secret keys to find your key ID
gpg --list-secret-keys --keyid-format LONG

The key ID is the hex string after the algorithm (e.g., rsa4096/3AA5C34371567BD2). Set it in Git:

git config --global user.signingkey YOUR_KEY_ID
git config --global gpg.program gpg

On some Linux systems, you may need gpg2 instead of gpg:

git config --global gpg.program gpg2

A hung or crashed GPG agent can cause signing failures. Restart it:

gpgconf --kill gpg-agent

Or more forcefully:

pkill -9 gpg-agent

The agent will automatically restart on the next GPG operation. You can also manually start it:

gpg-agent --daemon

If you're in an SSH session or headless environment, you need a terminal-based pinentry:

On Linux (Debian/Ubuntu):

sudo apt install pinentry-tty
sudo update-alternatives --config pinentry
# Select pinentry-tty from the list

Or configure manually:

echo "pinentry-program /usr/bin/pinentry-tty" >> ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent

On macOS with Homebrew:

brew install pinentry-mac
echo "pinentry-program $(which pinentry-mac)" >> ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent

If the issue persists, enable Git tracing to see exactly what's happening:

GIT_TRACE=1 git tag -s v1.0.0 -m "Test tag"

For even more detail on the GPG interaction:

GIT_TRACE=1 GIT_TRACE_SETUP=1 git tag -s v1.0.0 -m "Test tag" 2>&1 | head -50

This will show the exact GPG command Git is running and any error output.

Once GPG signing is working, create your signed tag:

git tag -s v1.0.0 -m "Release version 1.0.0"

Verify the signature:

git tag -v v1.0.0

You should see "Good signature from" followed by your key identity.