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

Kenny DuMez

Graphite software engineer

* * *

**Note**  
This guide explains this concept in vanilla Git. For Graphite documentation, see our [CLI docs](/content/docs/command-reference?utm_source=guidesCallout/index.html).

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.

### How Git commit signing works  
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.

### Generating a GPG key  
#### Step 1: Install GPG  
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`

#### Step 2: Generate a new GPG key  
To generate a new GPG key, use the following command:

```bash
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.

### Managing GPG keys  
#### Listing GPG keys  
To list all GPG keys stored on your system:

```bash
gpg --list-keys
```

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

```bash
gpg --export --armor <email> > publickey.asc
```

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

#### Importing a GPG key  
To import a GPG key from another user:

```bash
gpg --import publickey.asc
```

#### Deleting a GPG key  
To delete a GPG key from your keyring:

```bash
gpg --delete-key <email>
```

### Configuring Git to use your GPG key  
#### Step 1: Configure Git with your GPG key  
Find your GPG key ID:

```bash
gpg --list-keys
```

Configure Git to use this key by default:

```bash
git config --global user.signingkey <key-id>
```

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

#### Step 2: Sign commits using GPG  
To sign a commit, add the `-S` flag to the `git commit` command:

```bash
git commit -S -m "Your commit message"
```

### Verifying commit signatures  
To verify the signatures of commits, use:

```bash
git log --show-signature
```

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

### Handling common GPG errors  
- **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](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work).