Anyone can set any name and email in Git, which means commits can be impersonated. GPG commit signing cryptographically proves you authored a commit. In this tutorial, I will generate a GPG key pair, configure Git to sign commits automatically, and add the public key to GitHub so your commits display a verified badge. By the end, every commit you make will be cryptographically signed.
Prerequisites
- A Linux, macOS, or Windows machine with Git installed
- GPG installed (usually included on Linux and macOS)
- A GitHub, GitLab, or Bitbucket account (optional, for verified badges)
- Basic familiarity with Git commands
Step 1 - Install GPG
Check if GPG is already installed:
gpg --version
If you see version information, GPG is installed. If not, install it now.
On Ubuntu or Debian:
sudo apt update sudo apt install gnupg -y
On macOS with Homebrew:
brew install gnupg
On Windows, download and install GPG4Win from the official website.
Step 2 - Generate a GPG Key Pair
Create a new GPG key with the default settings:
gpg --full-generate-key
You will see a series of prompts:
1. Select the key type. Press Enter to accept the default (RSA and RSA).
2. Choose a key size. Enter 4096 for maximum security.
3. Set an expiration. Enter 1y for one year, or 0 for no expiration. I recommend 2y.
4. Confirm with y.
5. Enter your real name. This should match your Git commit name.
6. Enter your email address. Use the same email you commit with in Git.
7. Optionally add a comment, or leave blank.
8. Confirm with O for okay.
9. Enter a strong passphrase and confirm it. This protects your private key.
GPG will generate the key pair. This may take a minute. Move your mouse or type on the keyboard to generate entropy.
Step 3 - List Your GPG Keys
List your GPG keys to find the key ID:
gpg --list-secret-keys --keyid-format=long
You will see output like this:
sec rsa4096/ABC123DEF4567890 2024-01-15 [SC] [expires: 2026-01-15] uid [ultimate] Your Name <your.email@example.com> ssb rsa4096/1234567890ABCDEF 2024-01-15 [E] [expires: 2026-01-15]
The key ID is the part after rsa4096/ on the sec line. In this example, it is ABC123DEF4567890. Copy your key ID for the next steps.
Step 4 - Configure Git to Use Your GPG Key
Tell Git which GPG key to use for signing. Replace ABC123DEF4567890 with your key ID:
git config --global user.signingkey ABC123DEF4567890
Verify the configuration:
git config --global user.signingkey
You should see your key ID.
Also verify your Git name and email match the GPG key:
git config --global user.name git config --global user.email
If they do not match, update them:
git config --global user.name "Your Name" git config --global user.email "your.email@example.com"
Step 5 - Sign a Commit Manually
Make a test commit with the -S flag to sign it:
git commit -S -m "Test signed commit"
You will be prompted for your GPG passphrase. Enter it, and the commit will be signed.
Verify the commit signature:
git log --show-signature -1
You should see output including:
gpg: Signature made Mon Jan 15 12:34:56 2024 gpg: Good signature from "Your Name <your.email@example.com>"
This confirms the commit is cryptographically signed.
Step 6 - Enable Automatic Commit Signing
To sign every commit automatically without the -S flag, enable automatic signing globally:
git config --global commit.gpgsign true
Now every commit you make will be signed by default. Test it:
echo "test" > test.txt git add test.txt git commit -m "Auto-signed commit"
Check the signature again:
git log --show-signature -1
The commit should be signed even though you did not use the -S flag.
Step 7 - Export Your Public Key
To show verified badges on GitHub or GitLab, export your public key. Replace ABC123DEF4567890 with your key ID:
gpg --armor --export ABC123DEF4567890
This outputs your public key in ASCII format. It starts with BEGIN PGP PUBLIC KEY BLOCK and ends with END PGP PUBLIC KEY BLOCK. Copy the entire output including those lines.
Step 8 - Add Your Public Key to GitHub
Log in to GitHub and go to Settings, then click SSH and GPG keys in the sidebar. Click New GPG key.
Paste your public key into the text box and click Add GPG key.
GitHub will verify the key. Now any commits you push that are signed with this key will show a Verified badge.
For GitLab, go to Preferences, then GPG Keys, and paste your public key.
For Bitbucket, go to Personal settings, then GPG keys, and add your key.
Step 9 - Push a Signed Commit and Verify
Push your test repository to GitHub:
git push origin main
Visit your repository on GitHub and view the commit history. Your signed commits will display a green Verified badge next to them.
Click the badge to see details about the signature, including the key ID and fingerprint.
Step 10 - Troubleshoot GPG Agent Issues
If Git cannot find your GPG key or hangs waiting for a passphrase, you may need to configure the GPG agent. First, find the GPG binary path:
which gpg
Tell Git to use that GPG binary:
git config --global gpg.program /usr/bin/gpg
On macOS, if you installed GPG via Homebrew, the path might be /usr/local/bin/gpg or /opt/homebrew/bin/gpg.
If passphrase prompts do not appear, start the GPG agent manually:
gpg-agent --daemon
For persistent issues, add this to your shell profile:
export GPG_TTY=$(tty)
Then reload your shell:
source ~/.bashrc
Step 11 - Sign Tags
You can also sign Git tags. Create a signed tag:
git tag -s v1.0.0 -m "Release version 1.0.0"
Verify the tag signature:
git tag -v v1.0.0
You should see Good signature in the output. Signed tags prove that a release came from you and has not been tampered with.
Wrap-up
You have generated a GPG key pair, configured Git to sign commits automatically, and added your public key to GitHub for verified badges. Every commit you make is now cryptographically signed, proving your identity and preventing impersonation. Keep your private key secure and back it up. If you lose it, you cannot sign commits with the same identity. For teams, encourage everyone to sign commits so the entire history is verifiable and trusted.
