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

GitINTERMEDIATELOWUpdated Dec 6, 2025· 150 views

This error occurs when Git cannot use GPG to cryptographically sign a tag. Common causes include missing GPG_TTY configuration, expired keys, or misconfigured pinentry programs.

Quick fix

Fixes error: gpg failed to sign the data error: unable to sign the tag

export GPG_TTY=$(tty)
  1. Set the GPG_TTY environment variable
  2. Test GPG signing directly
  3. Check for expired GPG keys
  4. Verify Git's GPG configuration
git — error
export GPG_TTY=$(tty)
error: gpg failed to sign the data error: unable to sign the tag

What this error means

When you create a signed Git tag using `git tag -s` or `git tag -u <key-id>`, Git invokes GPG (GNU Privacy Guard) to create a cryptographic signature. This signature proves that the tag was created by someone with access to the private GPG key, providing authenticity and integrity verification for releases. The "gpg failed to sign the data" error indicates that the signing process failed at the GPG level. This can happen for several reasons: GPG cannot find the correct private key, the key has expired, the passphrase entry (pinentry) program cannot communicate with your terminal, or the GPG agent has crashed or become unresponsive. Unlike unsigned tags which are simple pointers to commits, signed tags create tag objects that include the tagger's identity, a timestamp, a message, and the cryptographic signature. This extra security is especially important for software releases, as it allows users to verify that a tagged version came from a trusted source.

Typical symptoms

  • Running 'git tag -s' or 'git tag -u' fails with 'gpg failed to sign the data'
  • The error message includes 'unable to sign the tag' or 'failed to write tag object'
  • Creating unsigned tags with 'git tag -a' works fine, but signed tags fail
  • The command 'echo test | gpg --clearsign' also fails or hangs
  • GPG signing works in GUI applications but fails in terminal or CI/CD environments

Common causes

  1. GPG_TTY environment variable is not set, preventing pinentry from accessing the terminal
  2. The GPG key configured for signing has expired
  3. The pinentry program cannot display a passphrase prompt (common in SSH sessions or CI/CD)
  4. Git is configured to use a signing key that doesn't exist or isn't available
  5. The GPG agent has crashed or is in a bad state and needs to be restarted
  6. On macOS, pinentry-mac is not installed or configured for Homebrew GPG installations

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

1Set the GPG_TTY environment variable

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

bash
export GPG_TTY=$(tty)

Add this to your shell configuration file for persistence:

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

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

Then reload your shell configuration:

bash
source ~/.bashrc  # or ~/.zshrc
2Test GPG signing directly

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

bash
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

3Check for expired GPG keys

List your GPG keys and check their expiration dates:

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

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

bash
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.

4Verify Git's GPG configuration

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

bash
# 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:

bash
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:

bash
git config --global gpg.program gpg2
5Restart the GPG agent

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

bash
gpgconf --kill gpg-agent

Or more forcefully:

bash
pkill -9 gpg-agent

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

bash
gpg-agent --daemon
6Configure pinentry for your environment

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

On Linux (Debian/Ubuntu):

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

Or configure manually:

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

On macOS with Homebrew:

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

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

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

For even more detail on the GPG interaction:

bash
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.

8Create the signed tag

Once GPG signing is working, create your signed tag:

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

Verify the signature:

bash
git tag -v v1.0.0

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

Advanced notes

### CI/CD and Automated Signing

In CI/CD pipelines, you typically cannot enter a passphrase interactively. Options include:

1. Use a key without a passphrase (less secure):

bash
gpg --batch --passphrase '' --quick-gen-key "CI Bot <ci@example.com>" default default never

2. Pre-cache the passphrase using gpg-preset-passphrase:

bash
echo "allow-preset-passphrase" >> ~/.gnupg/gpg-agent.conf
   gpgconf --kill gpg-agent
   /usr/lib/gnupg/gpg-preset-passphrase --preset KEYGRIP <<< "your-passphrase"

3. Use SSH signing (Git 2.34+) which can be easier to configure in CI:

bash
git config --global gpg.format ssh
   git config --global user.signingkey ~/.ssh/id_ed25519.pub

### Windows-Specific Issues

On Windows, if you installed GPG separately from Git for Windows:

1. Git may use its bundled GPG while your keys are in a different GPG installation
2. Add Git's GPG to your PATH: C:\Program Files\Git\usr\bin
3. Or point Git to your GPG: git config --global gpg.program "C:/Program Files (x86)/GnuPG/bin/gpg.exe"

### Hardware Security Keys (YubiKey)

If using a YubiKey or other hardware key:

1. Ensure the key is inserted and recognized: gpg --card-status
2. Touch may be required for each signing operation
3. The pinentry must support hardware token prompts

### Automatic Tag Signing

To automatically sign all annotated tags:

bash
git config --global tag.gpgSign true

Frequently asked questions

What does "error: gpg failed to sign the data error: unable to sign the tag" mean?
When you create a signed Git tag using git tag -s or git tag -u <key-id>, Git invokes GPG (GNU Privacy Guard) to create a cryptographic signature. This signature proves that the tag was created by someone with access to the private GPG key, providing authenticity and integrity verification for releases. The "gpg failed to sign the data" error indicates that the signing process failed at the GPG level.
How do I fix "error: gpg failed to sign the data error: unable to sign the tag"?
This error occurs when Git cannot use GPG to cryptographically sign a tag. Common causes include missing GPG_TTY configuration, expired keys, or misconfigured pinentry programs.
What causes "error: gpg failed to sign the data error: unable to sign the tag"?
GPG_TTY environment variable is not set, preventing pinentry from accessing the terminal The GPG key configured for signing has expired The pinentry program cannot display a passphrase prompt (common in SSH sessions or CI/CD)
Is the "error: gpg failed to sign the data error: unable to sign the tag" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading