Table of Contents
Main Steps
- Check GPG (GNU Privacy Guard) is Installed
- Import Keys
- List GPG Keys
- Configure Git to Use Your GPG Key
- Enable Commit Signing by Default (Optional)
- Sign a Commit
- Verify the Signed Commit
- Push Your Signed Commits
Additional Steps
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.
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>"
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
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:
| Time | User Key Activity | Passphrase? | Key Cache Expiry |
|---|---|---|---|
| 00:00 | 1st commit | Yes | 01:00 (due to default-cache-ttl) |
| 00:45 | Commit | No | 01:45 (expiry reset after commit) |
| 01:30 | Commit | No | 02:30 (expiry reset after commit) |
| 02:15 | Commit | No | 03:15 (expiry reset after commit) |
| 04:00 | none | N/A |
max-cache-ttl of 4 hours expired since 00:00 |
| 04:20 | Commit | Yes | 05:20 (new expiry after entering passphrase) |
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
Top comments (2)
Can't wait for this:
I'll update this soon to include how to modify key caching to prevent repeated passphrase entry.
I've added that under Additional Steps.