Getting Started with GPG Key Generation and Git Commit Signing

guide.md

Using GPG

Step 1: Install Required Software

We'll use the Homebrew package manager to install the necessary software.

brew install gpg2 gnupg pinentry-mac

Step 2: Create the .gnupg Directory

If the directory doesn't exist, create it and configure the pinentry program.

# Make the directory
mkdir ~/.gnupg

# Configure pinentry program
echo "pinentry-program $(brew --prefix)/bin/pinentry-mac" > ~/.gnupg/gpg-agent.conf

Step 3: Update or Create gpg.conf

Create or update the gpg.conf file to use the gpg-agent.

echo 'use-agent' > ~/.gnupg/gpg.conf

Step 4: Modify Shell Configuration

Add the following line to your shell configuration file (~/.bash_profile, ~/.bashrc, or ~/.zshrc):

export GPG_TTY=$(tty)

Step 5: Restart Your Terminal or Source Configuration

Restart your terminal or source the configuration file based on your shell:

• For macOS built-in bash: source ~/.bash_profile

• For bash through Homebrew over SSH: source ~/.bashrc

• For zsh: source ~/.zshrc

Step 6: Update Permissions on .gnupg Directory

Set secure permissions for the directory.

chmod 700 ~/.gnupg

Step 7: Restart GPG Agent

Ensure a freshly configured gpg-agent is launched.

killall gpg-agent

Step 8: Generate GPG Key

Generate a new GPG key with a 4096-bit length.

gpg --full-gen-key

During key generation, you'll be prompted through several options:

• Select key type: Choose RSA
• Choose keysize: Choose 4096 bits
• Set key validity: Key is valid for? Choose 0 (Key does not expire)

Note: Remember the key ID displayed in the output, as you'll need it for later steps.

Step 9: Provide Key Information

Answer questions to set up your GPG key:

• Real name: Your Full Name
• Email address: your.email@example.com

You'll also need to set a passphrase to protect your secret key.

Step 10: List Your Keys

List your generated keys.

gpg -k

Step 11: Get Short Key ID

Generate a short form of the key fingerprint.

gpg -K --keyid-format SHORT

Step 12: Export Key Fingerprint

Export the key fingerprint for GitHub. Replace <your key id> with the appropriate value from the previous step.

gpg --armor --export <your key id>

Step 13: Configure Git for GPG

Configure Git to use GPG.

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

Step 14: Configure Git Signing Key

Set your signing key in Git configuration. Replace <your key id> with the appropriate value from Step 8.

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

Step 15: Configure Git to Sign Commits (Optional)

Configure Git to sign all commits using the specified key.

git config --global commit.gpgsign true

Step 16: Perform a Signed Commit

Create a signed commit using the configured key.

git commit -S -s -m "My Signed Commit"

Step 17: Pinentry Prompt

Enter your signing key's passphrase when prompted by Pinentry.

Step 18: Submit GPG Key to GitHub

Add your GPG key to your GitHub account settings.