Signing Git Commits with GPG

Overview

Adding a GPG digital signature to Git commits allows you to prove the identity of the commit author and ensure code integrity.

This document introduces the concept of GPG and how it is used in Git.

It provides a step-by-step guide covering everything from GPG key generation to Git configuration and GitHub integration.

What is GPG?

GPG (GNU Privacy Guard) is open source encryption software for data encryption and digital signatures.

It follows the PGP (Pretty Good Privacy) standard and uses public-key cryptography.

Key Features

• Public-key encryption: Encrypts and decrypts data using a public/private key pair.
• Digital signatures: Signs data with a private key. Verifies the author’s identity and data integrity.
• Secure communication: Enables safe encryption and transmission of emails, files, and more.

Git and GPG

GPG is used in Git to add digital signatures to commits and tags.

• It allows you to prove that a commit was actually authored by you.
• Platforms like GitHub and GitLab display a Verified badge to increase trustworthiness.
• It prevents code tampering and forgery, strengthening project security.
• It protects files by encrypting them.

Why sign Git commits?

Git commit author information can be set arbitrarily by anyone using git config user.name and user.email.

Therefore, it is difficult to trust the actual author based on name and email alone.

By signing a commit with your private key before committing and registering your public key in a repository like GitHub, the platform can verify the signature and confirm whether the commit author matches.

Using GPG

Installing gnupg

gnupg: Install the package to use GPG (example: Mac)

1brew install gnupg

Key Generation

gpg --full-generate-key operates in interactive mode by default. Batch mode is also supported as an option.

1gpg --full-generate-key

Please select what kind of key you want: (1) RSA and RSA (2) DSA and Elgamal (3) DSA (sign only) (4) RSA (sign only) (9) ECC (sign and encrypt) default (10) ECC (sign only) (14) Existing key from card Your selection? 1

RSA keys may be between 1024 and 4096 bits long. What keysize do you want? (3072) 4096

Requested keysize is 4096 bits Please specify how long the key should be valid. 0 = key does not expire <n> = key expires in n days <n>w = key expires in n weeks <n>m = key expires in n months <n>y = key expires in n years Key is valid for? (0) 1y

Key is valid for? (0) 1y Key expires at 2027년 2월 16일 화요일 17시 14분 10초 KST Is this correct? (y/N) y

GnuPG needs to construct a user ID to identify your key.

Real name: your name Email address: your [email protected] Not a valid email address Email address: [email protected] Comment: test You selected this USER-ID: “your name (test) [email protected]”

Verifying Key Generation

1# List secret keys
2gpg --list-secret-keys
3
4# List public keys
5gpg --list-keys

Other Useful Features

1# Delete secret key
2gpg --delete-secret-keys {sec uuid}
3
4# Delete public key
5gpg --delete-keys {pub uuid}

1# Export secret key
2# gpg --armor --export-secret-keys {key_id} > private.asc
3gpg --armor --export-secret-keys 7XXXXXXXXXXXXXXXX6 > private.asc
4
5# Export public key
6# gpg --armor --export {key_id} > public.asc
7gpg --armor --export 7XXXXXXXXXXXXXXXX6 > public.asc

1#
2gpg --import private.asc
3
4# Set trust
5# gpg --edit-key {key_id}
6gpg --edit-key 7XXXXXXXXXXXXXXXX6
7
8# Verify registration
9gpg --list-secret-keys --keyid-format LONG

(Reference) Troubleshooting

Git Signing

When committing, you must sign with the private key linked to the GPG public key registered on GitHub.

GitHub will then verify the commit author when a signed commit is pushed.

The “Verified” badge will also appear next to the commit on GitHub.

Preparing GPG Signing in Git

Choose one of the options A, B, or C below.

Option A) Manual Signing (use -S per commit)

1git commit -S -m "Commit message"

Option B) Global Auto-Signing (all repositories)

1# Register GPG key ID (global)
2git config --global user.signingkey 7XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX6
3
4# Auto-sign commits (global)
5git config --global commit.gpgsign true
6
7# Verify settings
8git config --show-origin commit.gpgsign

Option C) Per-Repository Auto-Signing (specific repositories only)

 1# Navigate to repository
 2cd /path/to/repo
 3
 4# Register GPG key ID (local)
 5git config --local user.signingkey 7XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX6
 6
 7# Auto-sign commits (local)
 8git config --local commit.gpgsign true
 9
10# Verify settings
11git config --show-origin commit.gpgsign

Creating a GPG-Signed Commit

Add a signature when committing using the -S option.

1# Create a signed commit
2git commit -S -m "Commit message"
3
4# If auto-signing is configured
5git commit -m "Commit message"

Verify signing: Confirm that the commit was signed correctly.

1# Verify commit signature
2git log --show-signature
3
4# Or
5git verify-commit HEAD

(Reference) Troubleshooting

1**error: gpg failed to sign the data:**
2[GNUPG:] KEY_CONSIDERED 7E7DCEBF62463A41ACD992D8D9F62FE2379DF7E6 2
3[GNUPG:] BEGIN_SIGNING H8
4[GNUPG:] PINENTRY_LAUNCHED 42114 curses 1.3.2 - xterm-256color NONE - 501/20 0
5gpg: signing failed: Inappropriate ioctl for device
6[GNUPG:] FAILURE sign 83918950
7gpg: signing failed: Inappropriate ioctl for device
8**fatal: failed to write commit object**

GitHub Signing

GitHub and GPG

Registering your GPG public key on GitHub allows commit signatures to be verified.

When GitHub checks the signature of a pushed commit, it uses the registered GPG public key to verify whether the signature is valid.

If verification succeeds, a “Verified” badge is displayed next to the commit, proving that the commit was authored by the owner of the registered key.

This provides the following benefits:

• Identity verification: Proves that the commit was actually authored by you.
• Tamper prevention: Prevents others from making commits under your name.
• Increased trustworthiness: Clearly establishes the source of code in open source projects or team collaboration.

Registration Procedure

Register your GPG public key in the GPG keys section of your GitHub personal settings.

• Log in to GitHub and click the profile icon in the upper right.
• Select Settings.
• Click SSH and GPG keys in the left sidebar.
• In the GPG keys section, click the New GPG key button.
• Copy the entire public key content and paste it into the input field.
• Click the Add GPG key button to complete registration.

Once registered, the new key will appear in the GPG Keys list.

Looking Up Your GPG Public Key

1gpg --list-secret-keys --keyid-format LONG

Result

[keyboxd]

—-

pub rsa4096 2026-02-16 [SC] [expires: 2027-02-16] 7XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX6 ← {Key ID} uid [ultimate] Son Won Chul (plzhans’s macbook) [email protected] sub rsa4096 2026-02-16 [E] [expires: 2027-02-16] ← key expiration date

View the key content.

1# View key: gpg --armor --export {Key ID}
2gpg --armor --export 7XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX6

Registering a GPG Key on GitHub

Pushing to Repository

Push your signed commit to GitHub and the “Verified” badge will appear.

1git push origin main

Verifying Signed Commits and Tags

Related Posts

• Encrypting .env Files with GPG for Safe Commits
• age Usage Guide: Encrypt Team Secret Files with Recipients and Decrypt with Private Keys
• Completely removing leaked secrets from Git history with git filter-repo (force push and resync)