Signing your commits proves they came from you and haven’t been altered. Many organizations require signed commits to protect their supply chain. This step-by-step guide walks you through generating a GPG signing key, configuring Git to sign every commit and tag, uploading your public key to popular Git hosting services (GitHub, GitLab, Bitbucket), and troubleshooting common errors.
TL;DR (Quick Start)
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 repos.
Prerequisites
- Git 2.0+ (preferably newer).
- GnuPG 2.x (aka gpg or gpg2).
- A terminal (or PowerShell) and access to your Git hosting account.
1) Install GPG
macOS
On macOS, install GnuPG and the graphical pinentry program with Homebrew, then configure GPG to use the pinentry GUI.
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 || trueLinux
On Linux, install GnuPG and pinentry using your distribution’s package manager. The commands below cover Debian/Ubuntu and Fedora systems, and set GPG_TTY for proper passphrase prompts.
# Debian/Ubuntu
sudo apt update && sudo apt install -y gnupg pinentry-curses
# Fedora
sudo dnf install -y gnupg2 pinentry
# (Optional) ensure terminal pinentry works
echo 'export GPG_TTY=$(tty)' >> ~/.bashrc
export GPG_TTY=$(tty)Windows
On Windows, download and install Gpg4win (which includes Kleopatra) from gpg4win.org, then configure Git to use your GPG executable.
git config --global gpg.program "C:\\Program Files (x86)\\GnuPG\\bin\\gpg.exe"Tip (WSL): Prefer installing GPG inside WSL and run sudo apt install gnupg pinentry-curses. Then set the environment variable export GPG_TTY=$(tty) in your shell profile to ensure passphrase prompts work.
2) Create Your GPG Signing Key
Modern GPG (version 2.1 and later) makes it easy to create a signing key in one step. Generate a new Ed25519 signing key that expires after one year using the command below. Replace the name and email with your Git identity.
gpg --quick-generate-key "Your Name <you@example.com>" ed25519 sign 1yIf you prefer a more interactive approach, run the full key creation wizard. Choose the ECC/Ed25519 key type and specify a strong passphrase. Use the same name and email you use in Git. Afterwards, list your secret keys to find your new key’s fingerprint:
gpg --full-generate-key
# Choose: (9) ECC and ECC, then Curve: ed25519
# Use the same name and email as your Git identity, set a strong passphrase
gpg --list-secret-keys --keyid-format=long3) Configure Git to Always Sign
Configure Git to always sign your commits and tags with your new GPG key. Set your name and email, specify the full fingerprint as the signing key, and enable signing by default for commits and tags.
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 gpg4) Publish Your Public Key to Your Git Host
Export your public key in ASCII‑armored format so that your Git hosting service can verify signatures. Use the command below, substituting your key’s fingerprint. Then copy the contents of the generated file and paste it into your account settings on GitHub, GitLab, Bitbucket or other Git hosts.
gpg –armor –export > public-gpg-key.asc
5) Test Locally
Create a new file, add it to your repository, and commit it. Git will prompt for your GPG passphrase (once per session) and automatically sign the commit. Then verify the signature locally.
echo "signed" > demo.txt
git add demo.txt
git commit -m "chore: demo signed commit"
git log --show-signature -1
git verify-commit HEAD6) Sign Tags
Tags are often used for releases—sign them too.
git tag -s v1.0.0 -m "v1.0.0"
git push --tags
git tag -v v1.0.07) Use It in Your IDE
- VS Code: Enable ‘Git: Enable Commit Signing’ in settings and configure the GPG program path.
- JetBrains IDEs: In Preferences > Version Control > Git, turn on ‘Sign commits with GPG key’ and select your key.
- Other GUIs & CLI: Ensure a working pinentry program for passphrase prompts; set gpg.program if using a non-default path./heading
8) Key Maintenance & RotationExtend expiry: Use the interactive key editor (gpg –edit-key ), enter the ‘expire’ command to set a new expiration date, then run ‘save’ to store changes.
Revoke lost or compromised keys: Generate a revocation certificate now (gpg –output revoke.asc –gen-revoke ) and keep it offline. Import and publish revoke.asc if you ever need to revoke.
Back up secret keys: Export your private key securely (gpg –armor –export-secret-keys > private-backup.asc) and store it offline. Never commit private keys to source repositories or cloud drives.Security tip: Use a strong passphconsider hardware tokens (e.g., YubiKey) to store your signing key for added protection.rase and /heading
9) Troubleshooting (Quick Fixes)
consider hardware tokens (e.g., YubiKey) to store your signing key for added protection.