GPG Signature

A GPG signature is a way to cryptographically prove that a file or a commit really comes from you. This guide walks you through installing GPG, creating a signing key pair, signing your Git commits, and adding your public key to GitHub so your commits show up as "Verified".

Index

Installing GPG
Creating a signature
Signing Git commits with your gpg signature
Commit signature verification on GitHub

Installing GPG

Windows

Download Gpg4win at gnupg.org.

Linux

Debian/Ubuntu

apt update
apt install gnupg -y

Fedora/RedHat

dnf update -y
dnf install gnupg2 -y

Arch

gnupg should already be installed on your system as it is a dependency of pacman (ArchWiki).

pacman -S gnupg

macOS

If you don't have Homebrew installed, install it first at brew.sh, then run:

brew install gnupg

Creating a signature

Checking if gpg is installed

Open your terminal and run:

gpg --version

It should output:

[user@linux ~]$ gpg --version
gpg (GnuPG) 2.4.9
libgcrypt 1.12.2
Copyright (C) 2025 g10 Code GmbH
License GNU GPL-3.0-or-later <https://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Home: /home/user/.gnupg
Supported algorithms:
Pubkey: RSA, ELG, DSA, ECDH, ECDSA, EDDSA
Cipher: IDEA, 3DES, CAST5, BLOWFISH, AES, AES192, AES256, TWOFISH,
    CAMELLIA128, CAMELLIA192, CAMELLIA256
Hash: SHA1, RIPEMD160, SHA256, SHA384, SHA512, SHA224
Compression: Uncompressed, ZIP, ZLIB, BZIP2

After checking GPG is installed correctly, we should start creating a key.

Start creating your key pairs

gpg --full-generate-key

Heads up: this is an interactive wizard. It will ask you several questions and then a separate passphrase prompt. That passphrase prompt may open as its own window (a "pinentry" popup) - just type your passphrase there. On a server without a graphical interface it will instead ask you in the terminal.

It should display a prompt to specify what kind of key you want, press Enter to continue with the default or select what kind you want.

[user@linux ~]$ gpg --full-generate-key
gpg (GnuPG) 2.4.9; Copyright (C) 2025 g10 Code GmbH
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

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?

At the prompt, select which elliptic curve you want, press Enter to continue with the default or select what you want.

Please select which elliptic curve you want:
    (1) Curve 25519 *default*
    (4) NIST P-384
    (6) Brainpool P-256
Your selection?

Then when it asks you to specify the expiry time, press Enter to continue with the default or select what you want.

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)

If you entered 0 or Enter, then you should type y to confirm it.

Key does not expire at all
Is this correct? (y/N)

Input your real name

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

Real name:

Email address (use the verified email for GitHub)

Email address:

Enter comment or leave empty

Comment:

After all of this confirm that the inputted info is correct, if yes type O and continue. It should open a prompt to type your passphrase (use a secure passphrase).

Once finished it should generate your own gpg signature.

Output:

We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: directory '/home/user/.gnupg/openpgp-revocs.d' created
gpg: revocation certificate stored as '/home/user/.gnupg/openpgp-revocs.d/532E183AC87324997E2A064EC4D02E34E0956389.rev'
public and secret key created and signed.

pub   ed25519 2026-08-28 [SC]
      532E183AC87324997E2A064EC4D02E34E0956389
uid                      user <[email protected]>
sub   cv25519 2026-08-28 [E]

Note the two numbers at the end of the output: 532E183AC87324997E2A064EC4D02E34E0956389 is your key's full fingerprint, and C4D02E34E0956389 is the key ID - it's simply the last 16 characters of the fingerprint. You'll use the key ID later when telling Git which key to sign with.

Signing Git commits with your gpg signature

Now that we have our key, we need to tell Git to use it to sign our commits.

First, make sure Git knows who you are. The email you use here must match the email address you used in the GPG key (and the verified email on your GitHub account), otherwise GitHub will not show your commits as "Verified":

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Next, configure Git to use the GPG key we generated. Replace C4D02E34E0956389 with the key ID from your own output (the last 16 characters of your fingerprint):

git config --global user.signingkey C4D02E34E0956389

Enable signing for all commits by default:

git config --global commit.gpgsign true

Now every commit you make will be signed. To sign a single commit explicitly, use the -S flag:

git commit -S -m "Your commit message"

To verify that your commits are signed, use:

git log --show-signature

Windows only: if Git can't find Gpg4win's gpg binary, tell Git where it lives (adjust the path to your install):

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

Commit signature verification on GitHub

Run:

gpg --list-secret-keys --keyid-format=long

[keyboxd]
---------
sec   ed25519/C4D02E34E0956389 2026-08-28 [SC]
      532E183AC87324997E2A064EC4D02E34E0956389
uid                 [ultimate] user <[email protected]>
ssb   cv25519/88E544D3D639D488 2026-08-28 [E]

From the list of GPG keys, copy the key ID (the 16-character one) you'd like to use. In this example, the GPG key ID is C4D02E34E0956389:

gpg --armor --export C4D02E34E0956389
# Prints the GPG key ID, in ASCII armor format

Copy your GPG key, beginning with -----BEGIN PGP PUBLIC KEY BLOCK----- and ending with -----END PGP PUBLIC KEY BLOCK-----.

Add it on GitHub following this guide.

Verify it worked

1. Push a signed commit. Make a signed commit (or any commit, since signing is now enabled by default) and push it to GitHub:

git add .
git commit -m "Test signed commit"
git push

2. Check the badge. Open the commit on GitHub. You should see a green Verified badge next to your commit.

If the commit shows as "Unverified", the most common cause is an email mismatch. GitHub only shows "Verified" for commits made with a verified email address. To avoid this, you can use GitHub's noreply email instead of your personal one:

git config --global user.email "<id>+<username>@users.noreply.github.com"

You can find your own noreply address on GitHub under Settings → Emails.