GPG Sign Commits with GitHub Desktop on MacOS

gpg-commit-mac.md

GPG Sign Commits with GitHub Desktop on MacOS

Securing your git commits serves not only to verify your identity as the author but also to ensure the integrity of the codebase. This process, known as signing commits, utilizes GPG (GNU Privacy Guard) to attach a secure signature to your work. GitHub supports GPG signature verification which shows a "verified" label on commits to indicate they were securely signed.

This guide will walk you through the process of setting up GPG signing for your commits using GitHub Desktop on MacOS. The setup includes installing GPG, generating a new GPG key, adding it to your GitHub account, and configuring GitHub Desktop to automatically sign your commits. By the end of this guide, you’ll be able to sign your commits locally, strengthening the security and credibility of your contributions to any project.

Why Sign Your Commits?

Signing your commits with GPG adds an additional layer of security and trust to your workflow. It provides assurance that the commits were created by you, and have not been tampered with. In a team environment, this is particularly important for maintaining the integrity of the collaborative development process.

Now let's dive into the setup process.

Step 1: Install GPG

First, ensure you have GPG installed. If it's not installed, you can get it through Homebrew:

brew install gnupg

Step 2: Generate a GPG Key

If you don’t already have a GPG key, generate one:

gpg --full-generate-key

Follow the prompts to create your key. Choose RSA and RSA (default), set the key size (2048 or 4096 are common choices), and the expiration date. Then, enter your user ID information.

Step 3: List GPG Keys

After generating your key, list the existing keys to get your GPG key ID:

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

You’ll see output like:

/Users/you/.gnupg/secring.gpg
------------------------------
sec   4096R/<Your-Key-ID> 2023-01-01 [expires: 2027-01-01]
uid                          Your Name <your_email@example.com>

Your key ID is the alphanumeric string after 4096R/.

Step 4: Add GPG Key to GitHub

Copy your GPG key to the clipboard:

gpg --armor --export <Your-Key-ID>

Then, add this key to your GitHub account:

1. Go to GitHub and sign in.
2. Click on your profile photo, then click Settings.
3. In the user settings sidebar, click SSH and GPG keys.
4. Click New GPG key, paste your key, and click Add GPG key.

Step 5: Configure Git to Use the GPG Key

Now, configure Git to use this GPG key:

git config --global user.signingkey <Your-Key-ID>

To sign all commits by default in any local repository on your computer, run:

git config --global commit.gpgsign true

Step 6: Verify the Configuration

To check if everything is set up correctly, create a new commit in a repository and push it to GitHub. On GitHub, the commit should have a "Verified" label.

Step 7: Using GitHub Desktop

Now, when you use GitHub Desktop, your commits will be automatically signed if you've set commit.gpgsign to true. GitHub Desktop uses the underlying Git configuration for operations, so it will respect this setting.

Troubleshooting

If you encounter issues, ensure that GPG is correctly installed, your key is added to GitHub, and your Git configuration is pointing to the right GPG key. For more detailed instructions or troubleshooting, refer to the GitHub documentation.