> For the complete documentation index, see [llms.txt](https://docs.olympus-grid.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.olympus-grid.net/developer-guides/eos-ci-cd/signing-git-commits-with-gpg.md).

# Signing Git Commits with GPG

### **What is GPG?**

GPG (GNU Privacy Guard) is a cryptographic tool that allows users to encrypt and sign data, providing authentication and integrity verification. It is commonly used for secure email communication and verifying the authenticity of Git commits.

***

### **Installing GPG**

#### **MacOS**

On MacOS, install GPG using Homebrew:

```
brew install gnupg
```

After installation, verify it with:

```
gpg --version
```

#### **Windows**

On Windows, install GPG by downloading **Gpg4win** from <https://gnupg.org/download/>. After installation, verify it by opening a command prompt and running:

```
gpg --version
```

***

### **Generating a New GPG Key**

To create a new GPG key for signing Git commits, run:

```
gpg --full-generate-key
```

Follow the prompts:

* **Key type:** Select `RSA and RSA (default)`
* **Key size:** Enter `4096` for maximum security
* **Expiration:** Choose a duration (e.g., `1y` for one year)
* **User ID:** Provide your real name and email address
* **Passphrase:** Enter a secure passphrase to protect your key

After generation, list your keys with:

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

Find the newly created key and note the key ID, which appears as:

```
sec   rsa4096/XXXXXXXXXXXXXXXX  YYYY-MM-DD [SC] [expires: YYYY-MM-DD]
```

***

### **Configuring Git to Sign Commits**

#### **Set Your GPG Key in Git**

Replace `XXXXXXXXXXXXXXXX` with your actual key ID:

```
git config --global user.signingkey XXXXXXXXXXXXXXXX
```

Enable automatic signing of commits:

```
git config --global commit.gpgsign true
```

To verify your configuration:

```
git config --global --list | grep signingkey
```

#### **Export Your Public Key**

To use the GPG key for GitHub or other services, export it:

```
gpg --armor --export XXXXXXXXXXXXXXXX
```

Copy the output and add it to **GitHub → Settings → SSH and GPG keys → New GPG Key** ([GitHub Link](https://github.com/settings/keys)).

***

### **Testing GPG Signing with Git**

To test your setup, create and sign a commit:

```
echo "Test GPG signing" > testfile

git add testfile
git commit -S -m "Test commit with GPG signing"
git push
```

If successful, GitHub will display a **"Verified"** label next to the commit.

***

### **Additional GPG Commands**

#### **Listing GPG Keys**

To list your keys:

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

To list secret (private) keys:

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

#### **Backing Up Your GPG Key**

To back up your private key:

```
gpg --export-secret-keys --armor XXXXXXXXXXXXXXXX > private-key-backup.asc
```

Store this file securely.

To back up your public key:

```
gpg --export --armor XXXXXXXXXXXXXXXX > public-key-backup.asc
```

#### **Importing a GPG Key**

To import a key from a file:

```
gpg --import path/to/keyfile.asc
```

#### **Revoking a GPG Key**

If a key is compromised or lost, revoke it:

```
gpg --gen-revoke XXXXXXXXXXXXXXXX > revoke.asc
```

Then, import the revocation certificate:

```
gpg --import revoke.asc
```

***

### **Troubleshooting**

#### **Check if the GPG Agent is Running**

If you encounter issues signing commits, restart the GPG agent:

```
gpgconf --kill gpg-agent

gpgconf --launch gpg-agent
```

#### **Ensure Git is Using the Correct GPG Program**

Run:

```
git config --global gpg.program $(which gpg)
```

For GPG version 2.x, set:

```
git config --global gpg.program gpg2
```

#### **Manually Sign a File to Test GPG**

```
echo "test" > testfile.txt

gpg --clearsign testfile.txt
```

If successful, this generates a signed file `testfile.txt.asc`.

***

### **Conclusion**

Setting up GPG for Git signing ensures the integrity and authenticity of commits. By following this guide, developers can securely sign commits and contribute to repositories with verified identities.