Generating a GPG Key and Adding to Your GitHub Account

Generate and Configure a GPG Key for Verified Git Commits on GitHub

GPG (GNU Privacy Guard) is an open-source encryption tool that ensures data integrity through digital signatures and provides secure, verifiable authentication across various environments.

In Git, a version control system essential to modern development, commits are tied to an author's email address—making it susceptible to impersonation. To address this, platforms like GitHub recommend adding cryptographic signatures. When a GPG key is associated with a verified email on GitHub, signed commits are marked with a Verified badge, indicating they originate from a trusted source.

While private repositories on GitHub restrict access to approved collaborators, GPG signatures become especially valuable in collaborative scenarios involving third-party vendors or open-source contributors. They help prevent commit spoofing and maintain trust throughout the development workflow.

This article offers a brief overview of GPG and walks through the steps to generate a GPG key on macOS and link it to your GitHub account.

1. Understanding GPG and Its Core Principles

GPG (GNU Privacy Guard) is an open-source tool that encrypts data and verifies identity through digital signatures. Based on the PGP (Pretty Good Privacy) standard, it uses a hybrid model combining asymmetric and symmetric encryption—ensuring secure key exchange and efficient data protection.

Introduced in 1997 as part of the GNU Project, GPG has remained free to use and has earned lasting trust from the security community for its transparent implementation.

1-1. Core Algorithms Behind GPG Keys

The following algorithms are commonly used when generating a GPG key:

• Public-key encryption: Used for encrypting data or creating digital signatures.
  • RSA: A widely used, time-tested algorithm known for its reliability
  • ECC: A more modern choice that offers strong security with shorter keys
• Symmetric encryption: Algorithms like AES are used for actual data encryption due to their performance efficiency.
• Hash algorithms: Ensure data integrity and support signature generation.
• Compression and passphrase protection: Improve storage/transmission efficiency and protect private keys with a secure passphrase.

Together, these components produce a pair of keys—public and private—that support secure authentication and encryption across various use cases.

1-2. Real-World Applications of GPG

GPG is widely used beyond simple encryption, serving practical needs in secure software development:

• Commit signing: Adds cryptographic signatures to Git commits or tags to prevent spoofing and display Verified badges on GitHub.
• Software integrity: Verifies release artifacts by signing files during distribution.
• Email encryption: Secures sensitive content and authenticates senders.
• Secure server communication: Prevents man-in-the-middle attacks by validating encrypted channels.

In environments where trust, authenticity, and collaboration are essential, GPG plays a critical role in maintaining security and integrity.

2. Installing GPG Utilities

After reviewing the fundamentals and real-world uses of GPG, we now move on to installing the necessary tools to create a GPG key on macOS.

2-1. Install the GPG Key Generation Tool

On macOS, you can install GPG easily using Homebrew, a popular package manager.

Run the following command in your terminal to install the gnupg package:

$ brew install gnupg

Once installation is complete, verify that GPG is working correctly by checking the version:

$ gpg --version
gpg (GnuPG) 2.4.7
libgcrypt 1.11.0
...

2-2. Install Pinentry on macOS

GPG requires a passphrase prompt when signing. On macOS, this prompt may not appear in certain setups. Installing Pinentry Mac can help prevent this, but if you don’t encounter any issues, you can safely skip this step.

If you’d like to avoid potential issues, consider installing Pinentry Mac:

$ brew install pinentry-mac

Next, configure the GPG agent to use pinentry-mac by appending the following line to your config:

$ echo "pinentry-program /opt/homebrew/bin/pinentry-mac" >> ~/.gnupg/gpg-agent.conf

Apply the changes by restarting the GPG agent:

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

To confirm that Pinentry is working properly, run the following command and check if a passphrase prompt appears:

$ echo "testing GPG Signing" | gpg --clearsign

• gpg --clearsign: hashes the input and attaches a digital signature block.

If the passphrase prompt appears as expected, the setup is complete. Pinentry Mac also integrates with macOS Keychain, allowing saved passphrases to be reused automatically.

After entering the passphrase, you should see a signed output like the example below:

$ echo "testing gpg signing" | gpg --clearsign
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

testing gpg signing
-----BEGIN PGP SIGNATURE-----

iQI*************************************************************
****************************************************************
****************************************************************
****************************************************************
****************************************************************
-----END PGP SIGNATURE-----

3. Generating a New GPG Key

The process of creating a new GPG key using GnuPG on macOS involves several interactive steps:

3-1. Start the Key Generation Process

Run the following command to begin:

$ gpg --full-generate-key

3-2. Select the Key Type

Choose the type of key to generate. RSA has long been considered a reliable choice due to its widespread adoption and proven security. However, its relatively large key size can lead to slower performance and more complex key management.

In contrast, ECC (the default option) offers equivalent security with shorter key lengths, making it a more efficient option—especially in resource-constrained environments like mobile and IoT devices. Both are valid choices; select the one that best suits your needs. In this case, we’ll proceed with RSA:

Please select what kind of key you want:
   (1) RSA and RSA
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
   (9) ECC (sign and encrypt) *default*
  (10) ECC (sign only)
  (14) Existing key from card
Your selection? 1

3-3. Specify the Key Size

Set the key length. For stronger security, 4,096 bits is recommended:

RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (3072) 4096
Requested keysize is 4096 bits

3-4. Define the Key Expiration

Decide how long the key should remain valid. Enter 0 for no expiration:

Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0) 0

3-5. Provide User Information

Enter your identity details. The name and email are used to associate the key with the author of commits, and an optional comment can help clarify the key’s purpose:

Real name: Jin 🐈
Email address: catsriding@gmail.com
Comment: Made with 💖 by Jin 🐈, featuring Ongs and Mongs 🐾

• Real name: Displayed as the author name in Git commits.
• Email: Tied to your GitHub account for verifying signatures.
• Comment: Optional. Useful for identifying the key at a glance.

3-6. Confirm Your Input

Review the details. If everything looks correct, enter O to continue:

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o

3-7. Set Passphrase

Protect your private key with a secure passphrase. You’ll be prompted for it whenever the key is used:

┌─────────────────────────────────────────────────────────────┐
│ Please enter the passphrase to                              │
│ protect your new key                                        │
│                                                             │
│ Passphrases match.                                          │
│                                                             │
│ Passphrase: _______________________________________________ │
│                                                             │
│ Repeat: ___________________________________________________ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │                                                         │ │
│ └─────────────────────────────────────────────────────────┘ │
│        <OK>                                   <Cancel>      │
└─────────────────────────────────────────────────────────────┘

3-8. Wait for the Key Generation Process

Once configuration is complete, the key will be generated. GPG may request additional system activity (like typing or moving the mouse) to collect enough entropy:

We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: /Users/catsriding/.gnupg/trustdb.gpg: trustdb created
gpg: directory '/Users/catsriding/.gnupg/openpgp-revocs.d' created
gpg: revocation certificate stored as '/Users/catsriding/.gnupg/openpgp-revocs.d/3FE********************.rev'
public and secret key created and signed.

pub   rsa4096 2025-01-15 [SC]
      3FE********************
uid                      Jin 🐈 (Made with  💖 by Jin 🐈, featuring Ongs and Mongs 🐾) <catsriding@gmail.com>
sub   rsa4096 2025-01-15 [E]

3-9. Verify the Generated Key

Finally, confirm that your new key has been created successfully:

$ gpg --list-secret-keys --keyid-format LONG
gpg: checking the trustdb
gpg: marginals needed: 3  completes needed: 1  trust model: pgp
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
[keyboxd]
---------
sec   rsa4096/22F************ 2025-01-15 [SC]
      3FE********************
uid                 [ultimate] Jin 🐈 (Made with  💖 by Jin 🐈, featuring Ongs and Mongs 🐾) <catsriding@gmail.com>
ssb   rsa4096/D0************* 2025-01-15 [E]

With that, your GPG key is ready for use.

4. Linking Your GPG Key with Git and GitHub

Git identifies commit authors based on their email addresses, which creates a potential risk—anyone can forge a commit by spoofing that address. To mitigate this, it’s strongly recommended to use cryptographic signatures. One common approach is to associate your commits with a GPG key.

4-1. Enable Commit Signing in Git

To sign all commits automatically, you need to configure Git with your GPG key. While it’s possible to manually sign each commit using the -S flag, applying the setting globally is much more convenient.

First, check the list of GPG secret keys stored on your system:

$ gpg --list-secret-keys

You’ll see output similar to the following. The sec section contains your GPG key ID:

[keyboxd]
---------
sec   rsa4096 2025-01-15 [SC]
      3FE********************  # GPG_KEY_ID
uid           [ultimate] Jin 🐈 (Made with 💖 by Jin 🐈, featuring Ongs and Mongs 🐾) <catsriding@gmail.com>
ssb   rsa4096 2025-01-15 [E]

Now configure Git to use this key:

$ git config --global user.signingkey <GPG_KEY_ID>
$ git config --global commit.gpgsign true
$ git config --global gpg.program $(which gpg)

To verify the settings, inspect your Git config file:

$ cat ~/.gitconfig
───────┬───────────────────────────────────────────────────────────────
       │ File: /Users/catsriding/.gitconfig
───────┼───────────────────────────────────────────────────────────────
   1   │ [user]
   2   │     email = catsriding@gmail.com
   3   │     name = Jin 🐈
   4   │     signingkey = 3FE********************
   5   │ [commit]
   6   │     gpgSign = true
   7   │ [tag]
   8   │     forceSignAnnotated = false
   9   │ [gpg]
  10   │     format = openpgp
  11   │     program = /opt/homebrew/bin/gpg
───────┴───────────────────────────────────────────────────────────────

Let’s confirm that signing is working properly by creating a sample commit:

$ echo "Testing GPG signing" > hello-gpg.md
$ git add hello-gpg.md
$ git commit -m "🧪 test: test gpg signing"

Then run the following to check the commit signature:

$ git log --show-signature -n 1
commit 419354ae2214e517dfe321df6ea256dda3e8e370 (HEAD -> waves)
gpg: Signature made Thu Jan 15 21:03:10 2025 KST
gpg:                using RSA key 3FE********************
gpg: Good signature from "Jin 🐈 (Made with 💖 by Jin 🐈, featuring Ongs and Mongs 🐾) <catsriding@gmail.com>" [ultimate]
Author: Jin 🐈 <catsriding@gmail.com>
Date:   Thu Jan 15 21:03:10 2025 +0900

    🧪 test: test gpg signing

If you see Good signature from, everything is set up correctly. If not, review your configuration or GPG key setup.

4-2. Add your GPG key to GitHub

To allow GitHub to verify your signed commits, add your GPG public key to your GitHub account.

Export your public key with the following command:

$ gpg --armor --export <GPG_KEY_ID>
-----BEGIN PGP PUBLIC KEY BLOCK-----
mQI*************************************************************
****************************************************************
****************************************************************
****************************************************************
****************************************************************
...
-----END PGP PUBLIC KEY BLOCK-----

Copy the entire block, including the BEGIN and END lines.

Next, go to SSH and GPG keys settings on GitHub, and click New GPG key.

Paste your public key into the field and click Add GPG Key.

If you have two-factor authentication enabled, GitHub will prompt you to verify your identity:

Once added, your key will appear in the GPG keys list:

From now on, signed commits made with this key will show a Verified badge in your commit history:

If you’re using a Git GUI like GitKraken, check if it provides built-in GPG key generation features:

5. Wrapping Up Git and GPG Key Integration

We’ve covered the full process of generating a GPG key and connecting it to GitHub. By signing your Git commits and tags, you strengthen the authenticity of your contributions and protect your account from impersonation. From now on, you can contribute to your projects with Verified commits that reinforce trust and transparency. 🚀

---

• 🔗 GNU Privacy Guard Docs
• 🔗 GitHub Docs