Configure Git to Sign All Your Commits with GPG (Step‑by‑Step)

Signing your commits proves they came from you and haven’t been altered. Many teams now require signed commits to protect their supply chain. In this guide you’ll generate a GPG key, configure Git to sign every commit and tag, upload your public key to GitHub/GitLab/Bitbucket and fix common errors.

---

TL;DR (copy–paste quick start)

# 1) Install GPG
# macOS
brew install gnupg pinentry-mac
# Ubuntu/Debian
sudo apt update && sudo apt install -y gnupg pinentry-curses
# Fedora
sudo dnf install -y gnupg2 pinentry
# Windows: install Gpg4win from https://www.gpg4win.org/

# 2) Create a signing key (Ed25519, signing-only, 1-year expiry)
gpg --quick-generate-key "Your Name <you@example.com>" ed25519 sign 1y

# 3) Find your key’s fingerprint
gpg --list-secret-keys --keyid-format=long
# copy the 40-hex-character fingerprint (not just the short ID)

# 4) Tell Git to always sign
git config --global user.name  "Your Name"
git config --global user.email "you@example.com"
git config --global user.signingKey <YOUR_FINGERPRINT>
git config --global commit.gpgsign true
git config --global tag.gpgSign  true
git config --global gpg.program  gpg

# 5) Export your public key and add it to your Git host (GitHub/GitLab/etc.)
gpg --armor --export <YOUR_FINGERPRINT> > public-gpg-key.asc
# Upload the contents of public-gpg-key.asc to your Git hosting account.

# 6) Test
echo "test" > signed.txt && git add signed.txt && git commit -m "feat: signed commit"
git log --show-signature -1

---

Why Sign Commits?

• Authenticity – Proves the author is really you.
• Integrity – Detects tampering after a commit is made.
• Compliance – Many organizations require “Verified” commits for critical repositories.

---

Prerequisites

• Git 2.0 or newer.
• GnuPG 2.x (gpg or gpg2).
• A terminal (or PowerShell) and access to your Git hosting account.

---

1) Install GPG

Install GPG using your platform’s package manager. Here are commands for common platforms:

macOS
Use Homebrew to install GnuPG and the pinentry helper, then enable the GUI pinentry:

brew install gnupg pinentry-mac
# enable the macOS pinentry UI
mkdir -p ~/.gnupg
echo "pinentry-program /opt/homebrew/bin/pinentry-mac" >> ~/.gnupg/gpg-agent.conf
killall gpg-agent 2>/dev/null || true

Linux (Debian/Ubuntu)
Install GnuPG and a curses-based pinentry program, then set your TTY for passphrase prompts:

sudo apt update && sudo apt install -y gnupg pinentry-curses
# optional: ensure terminal pinentry works
echo 'export GPG_TTY=$(tty)' >> ~/.bashrc
export GPG_TTY=$(tty)

Linux (Fedora)
Install GnuPG 2 and pinentry using dnf:

sudo dnf install -y gnupg2 pinentry

Windows
Install Gpg4win (includes Kleopatra). After installation, ensure Git uses the correct gpg.exe by configuring:

git config --global gpg.program "C:\\Program Files\\GnuPG\\bin\\gpg.exe"

Tip (WSL): Prefer installing GPG inside WSL using sudo apt install gnupg pinentry-curses and set export GPG_TTY=$(tty) so pinentry can prompt correctly.

2) Create Your GPG Signing Key

Generate a signing‑only Ed25519 key that expires after one year. This modern command requires GnuPG 2.1 or newer and avoids the interactive prompts:

gpg --quick-generate-key "Your Name <you@example.com>" ed25519 sign 1y

If you prefer the interactive wizard, you can generate a signing key by running the full key generator and answering the prompts. Select ECC with curve Ed25519, use the same name and email as your Git identity, and choose a strong passphrase.

gpg --full-generate-key
# Choose: (9) ECC and ECC, then curve: ed25519
# Use your name and email and set a strong passphrase

After generating your key, list your secret keys and copy the full 40‑character fingerprint (not just the short key ID) for use in Git configuration.

gpg --list-secret-keys --keyid-format=long
# copy the 40-character fingerprint

3) Configure Git to Always Sign

Run the following commands to set your name and email, tell Git which key to use, and sign commits and tags by default.

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global user.signingKey <YOUR_FINGERPRINT>
git config --global commit.gpgsign true
git config --global tag.gpgSign true
git config --global gpg.program gpg

4) Publish Your Public Key to Your Git Host

Export your public key in ASCII‑armored format and add it to your Git hosting account (GitHub, GitLab, Bitbucket, etc.).

gpg --armor --export <YOUR_FINGERPRINT> > public-gpg-key.asc

Upload the contents of the generated public-gpg-key.asc file to your Git hosting service’s GPG key settings page.

5) Test Locally

Create a test file, make a signed commit, and confirm that Git prompts for your GPG passphrase. This proves everything is wired up correctly.

echo "signed" > demo.txt
git add demo.txt
git commit -m "chore: demo signed commit"

Verify the signature of the last commit using the following commands.

git log --show-signature -1
# or
git verify-commit HEAD

6) Sign Tags

Tags are often used for releases, so you should sign them as well to provide provenance.

git tag -s v1.0.0 -m "v1.0.0"
git push --tags
git tag -v v1.0.0

7) Use It in Your IDE

• VS Code: In Settings, search for “sign commit” and enable “Git: Enable Commit Signing”; set Git: GPG Path to your gpg executable (e.g., gpg or C:\Program Files\GnuPG\bin\gpg.exe).
• JetBrains IDEs (IntelliJ, WebStorm, etc.): Under Preferences → Version Control → Git, enable “Sign commits with GPG key” and select your key.
• Git GUIs: If a graphical client fails to prompt for your passphrase, ensure a working pinentry program is installed and configured (see troubleshooting).

8) Key Maintenance & Rotation