Importing and Using Existing GPG Keys to Sign Git Commits

Table of Contents

Main Steps

1. Check GPG (GNU Privacy Guard) is Installed
2. Import Keys
3. List GPG Keys
4. Configure Git to Use Your GPG Key
5. Enable Commit Signing by Default (Optional)
6. Sign a Commit
7. Verify the Signed Commit
8. Push Your Signed Commits

Additional Steps

• GitHub/GitLab Setup Resources
• Prevent Repeated Passphrase Entry with GPG Key Caching

Main Steps

1. Install and Check GPG (GNU Privacy Guard)

Install GPG through your package manager, like apt, brew, dnf, pacman, yum, zypper, etc. You may need to prepend sudo.

brew install gnupg

gpg --version

2. Import Keys

Instead of manually placing keys into specific folders, you should import your existing keys using GPG commands. This way, GPG will handle storing the keys properly within its internal keyring.

To import private and public keys:

gpg --import ~/my-backup-keys/private-key.asc  # Import private key
gpg --import ~/my-backup-keys/public-key.asc   # Import public key

3. List GPG Keys

 gpg --list-secret-keys --keyid-format LONG

Output

 /home/user/.gnupg/secring.gpg
 ------------------------------------
 sec   4096R/ABCDEF1234567890 2023-01-01 [expires: 2025-01-01]
 uid                          Your Name <your.email@example.com>
 ssb   4096R/1234567890ABCDEF 2023-01-01

The ABCDEF1234567890 part is the key ID.

4. Configure Git to Use Your GPG Key

Set the GPG key for the specific repository (or globally for all repositories).

Specific repo:

 git config user.signingkey ABCDEF1234567890

Globally:

 git config --global user.signingkey ABCDEF1234567890

Replace ABCDEF1234567890 with your actual GPG key ID.

Back to Top

5. Enable Commit Signing by Default (Optional)

You can configure Git to sign all commits by default.

Specific repo:

 git config commit.gpgSign true

Globally:

 git config --global commit.gpgSign true

6. Sign a Commit

Manually
If you don’t enable signing by default, you can sign a commit manually by using the -S option:

 git commit -S -m "Your commit message"

Automatic

git commit -m "Your commit message"

Passphrase Prompt
If your GPG key is passphrase-protected, which is highly recommended, you’ll be prompted to enter the passphrase whenever you sign a commit. See "Prevent Repeated Passphrase Entry with GPG Key Caching" to cache the key and prevent repeated passphrase entry for a timespan.

7. Verify the Signed Commit

You can verify that your commit was signed by using:

 git log --show-signature

It should show something like:

 commit abcdef1234567890abcdef1234567890abcdef12 (HEAD -> main)
 gpg: Signature made Mon 01 Jan 2023 12:00:00 PM UTC using RSA key ID ABCDEF1234567890
 gpg: Good signature from "Your Name <your.email@example.com>" 

Back to Top

8. Push Your Signed Commits

Before being able to push, you'll need to ensure your GPG key is added to your remote repo account. See "GitHub/GitLab Setup Resources".
Now, when you push your commits, they will be signed with your GPG key.

git push origin main

Additional Steps

GitHub/GitLab Setup Resources

If you’re using GitHub or GitLab, make sure your GPG key is added to your account.

• For GitHub: Adding a GPG Key
• For GitLab: Adding a GPG Key

Back to Top

Prevent Repeated Passphrase Entry with GPG Key Caching

The gpg-agent tool can be used to prevent repeated passphrase entry for multiple commits during a timespan.

1. Locate or Create gpg-agent Configuration File

It is usually named gpg-agent.conf and is located in your .gnupg directory, which is typically ~/.gnupg/gpg-agent.conf.

If it doesn’t exist, you can create it: touch ~/.gnupg/gpg-agent.conf

2. Edit the gpg-agent Configuration

Open the gpg-agent.conf file with a text editor, and you can set the following options:

• default-cache-ttl: This sets the time in seconds that the passphrase is cached. The default is usually 600 seconds (10 minutes).
• max-cache-ttl: This sets the maximum time in seconds that the passphrase is cached after the first time it is used. The default is usually 7200 seconds (2 hours).

For example, to cache the passphrase for 1 hour and allow it to be cached for a maximum of 4 hours after first use, add these lines and save the file:

default-cache-ttl 3600
max-cache-ttl 14400

Scenario

Continuing with the example Time To Live (TTL) values, say you add your key to the agent at 00:00 during your 1st commit of the session and enter the passphrase.
Subsequent commits at 00:45, 1:30, and 2:15 will each extend the cache expiry by an hour, until 4 hours since the initial passphrase entry at 00:00, as long as the key is used contiguously within 1-hour intervals of each other:

3. Restart gpg-agent

Restart the agent for changes to take effect:

gpgconf --kill gpg-agent
gpgconf --launch gpg-agent

4. Verify Configuration

Ensure your configuration changes are recognized by checking the active configuration with:

gpgconf --list-options gpg-agent

Back to Top