Read Anthropic’s case study about Graphite Reviewer

How to use GPG keys to sign and verify Git commit signatures

Kenny DuMez
Kenny DuMez
Graphite software engineer


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


Signing a commit using a GPG key is a way to securely authenticate the commit's origin by attaching a digital signature to it. This signature confirms that the commit was made by a specific person who possesses the corresponding private GPG key and can be trusted. The process involves using cryptographic techniques to generate a unique signature based on the commit data and the private key of the signer.

When you sign a commit, Git uses your private GPG key to create a digital signature. This signature is unique to the specific commit content; any change in the commit would result in a different signature. The signature is then attached to the commit itself. Since the private key is secret and should only be accessible by its owner, the presence of a valid signature is strong evidence that the commit was indeed created by the owner of the corresponding public key.

First, ensure that GPG is installed on your system. You can install it through your operating system's package manager:

  • For Ubuntu/Debian: sudo apt-get install gnupg
  • For Fedora: sudo dnf install gnupg
  • For macOS (using Homebrew): brew install gnupg

To generate a new GPG key, use the following command:

Terminal
gpg --full-generate-key

During the key generation process, you will be prompted to select the type of key, key size, and expiration date. You will also need to provide user identification information such as your name and email address, which should match your Git configuration.

To list all GPG keys stored on your system:

Terminal
gpg --list-keys

After creating your GPG key, you need to export your public key to share it with others or add it to services like GitHub:

Terminal
gpg --export --armor <email> > publickey.asc

Replace <email> with the email address used during the key generation.

To import a GPG key from another user:

Terminal
gpg --import publickey.asc

To delete a GPG key from your keyring:

Terminal
gpg --delete-key <email>

Find your GPG key ID:

Terminal
gpg --list-keys

Configure Git to use this key by default:

Terminal
git config --global user.signingkey <key-id>

Replace <key-id> with the ID of your GPG key.

To sign a commit, add the -S flag to the git commit command:

Terminal
git commit -S -m "Your commit message"

To verify the signatures of commits, use:

Terminal
git log --show-signature

This command provides details on who signed each commit and whether the signature can be verified.

  • GPG: decryption failed: no secret key: This error occurs when you try to decrypt a message or verify a signature but don't have the appropriate private key. Ensure you have the private key that matches the public key used for signing.

  • Key is stored in legacy trusted.gpg keyring: Modern GPG versions recommend using gpg instead of the older gpg2 and storing keys in a new keyring format. You might need to migrate your keys to the new format.

For further reading on signing Git commits with a GPG key, see the official Git documentation.

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2