1  GPG Commit Signing

1.1 Introduction

Using GPG to sign commits provides crucial benefits related to security, trust, and accountability by cryptographically verifying the author’s identity and ensuring the code’s integrity.

The primary benefits include:

  • Authenticity and Identity Verification: It proves that a commit actually originated from you rather than someone spoofing your name and email address. In standard Git, anyone can change their local configuration to pretend to be another developer.
  • Tamper-Evidence: A GPG signature ensures that the commit’s contents (the code changes, message, and metadata) have not been altered since it was signed. If a single bit is changed, the cryptographic hash will no longer match the signature.
  • “Verified” Status on Platforms: Major hosting services like GitHub, GitLab, and Bitbucket display a green “Verified” badge next to signed commits, which builds trust with maintainers and collaborators.
  • Audit Trails and Compliance: For organizations with strict security or legal requirements, signed commits provide an immutable, auditable trail of who authorized specific changes to the codebase.
  • Protection Against Infrastructure Compromise: If a Git server itself is compromised, GPG signatures remain valid because they were created locally with your private key, allowing others to verify that the historical code is still legitimate.
  • Enforcement of Security Policies: Repository administrators can enable branch protection rules that reject unsigned commits, ensuring that only verified contributions enter critical branches.

1.2 GnuPG

GnuPG: gpg version 2.x is installed along with Git for Windows, so there is no need to install it separately. All of the following command can be run in the Git bash terminal available in RStudio, Positron, VS Code, etc.

If you plan to use the utilities distributed with git at the Windows command prompt, you must add the ensure that the Git usr/bin (i.e., C:Files) directory is included Environment Variables PATH.

For complete documentation see the GNU Privacy Handbook.

# Which gpg executable is currently being used?
where gpg

# What version is being used?
gpg --version

# Where are keys being stored?
gpg --list-secret-keys --keyid-format=long
  • Recent versions of Git have will have gpg version 2.x in the C:\Program Files\Git\usr\bin directory.
  • Add this folder to Path environment variable for your account.
  • After making this path change, reopen your IDE (PyCharm, RStudio), and run the above commands again to confirm gpg is using the specified gpg version.

1.3 Set git default editor

Change git’s default editor from vim to nano.

git config --global core.editor "nano"

1.4 Generating a new GPG key

Generating a new GPG key * Open a shell/terminal window in your current working directory (root of git repo) and run the following commands:

# Generate a GPG key using version 1 syntax
gpg --gen-key
# List the GPG keys on the current cumputer
gpg --list-secret-keys --keyid-format=long
# --list-secret-keys output:
D:\Workspace\rarr>gpg --list-secret-keys --keyid-format=long
/c/Users/B5PMMMPD/.gnupg/pubring.gpg
------------------------------------
sec   2048R/B68FE334FA0C2722 2022-03-04
uid                          Michael Dougherty <mike.p.doc.71@gmail.com>
ssb   2048R/91484B4037C3D166 2022-03-04
  • In the example above, the <key id> that you will use in the next step is: B68FE334FA0C2722
  • In the example above, this key can be referenced using its uid: mike.p.doc.71@gmail.com

1.5 Set Git to use this signing key

Telling Git about your signing key

# Set user name and email
git config --global user.name "Your Name"
git config --global user.email you@example.com

# Set signing key on the current computer
git config --global user.signingkey <key id>

# Set git to sign all commits on the current computer
git config --global commit.gpgsign true

1.6 Set the trust level of this key

The following commands will set the computer’s GPG trust database.

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

# At the gpg prompt, enter the `trust` command to set the trust level
gpg> trust

# Follow the prompts to set "ultimate" trust level for this key.
# Save your changes
gpg> save
# Quit without saving changes
gpg> quit

1.7 Test your new signing key

# in a git repo
touch test.txt
git add test.txt
git commit -m "test signed commits"
# View signatures of each commit
git log --show-signature

1.8 Export public GPG keys

Export GPG key

# List the GPG public keys on the current computer
gpg --list-public-keys --keyid-format=long

# List the GPG secret keys on the current computer
gpg --list-secret-keys --keyid-format=long

# Prints the GPG public key, in ASCII armor format
gpg --armor --export <key>
  • Copy your GPG public key, beginning with -----BEGIN PGP PUBLIC KEY BLOCK----- and ending with -----END PGP PUBLIC KEY BLOCK-----.
  • Copy this text to your encrypted password database.
  • Save the database.

1.9 Export your GPG private key for use on another computer

Import your GPG key on another computer

# From the first computer where you generated the GPG key, export the 
# ASCII armored private key
gpg --armor --export-secret-keys <key>
  • Copy your GPG private key, beginning with -----BEGIN PGP PRIVATE KEY BLOCK----- and ending with -----END PGP PRIVATE KEY BLOCK-----.
  • Add the exported text of the GPG private key to your secure password database.
  • Save the database.
  • This will allow you to install this GPG private key on any other computers you use.

1.10 Adding a new GPG public key to your GitHub account

Adding a new GPG key to your GitHub account

  • Add the GPG public key to GitHub.

1.11 Check your signed commit

Check your signed commit

# in a git repo
touch test.txt
git add test.txt
git commit -m "test signed commits"

1.12 Import your GPG public and private key on another computer

  • On another computer, open your secure password database.
  • Copy the public key text to a temp file named mykey_pub.txt in your shell’s current working directory.
  • Copy the private key text to a temp file named mykey_sec.txt in your shell’s current working directory.
# Import the GPG public key
gpg --import mykey_pub.txt

# Check that the GPG public key imported correctly
gpg --list-public-keys --keyid-format=long

# Import the GPG private key
gpg --allow-secret-key-import --import mykey_sec.txt

# Check that the GPG private key imported correctly
gpg --list-secret-keys --keyid-format=long
  • If the key imports are successful, delete these temporary files to ensure the security of your private key.

1.13 Set Git to use this signing key

Telling Git about your signing key

# Set user name and email
git config --global user.name "Your Name"
git config --global user.email you@example.com

# Set signing key
git config --global user.signingkey <key id>

# Set git to sign all commits
git config --global commit.gpgsign true

1.14 Set the trust level of this key

The following commands will set the computer’s GPG trust database.

gpg --edit-key mike.p.doc.71@gmail.com

# At the gpg prompt, enter the `trust` command to set the trust level
gpg> trust
gpg> save