Select Page

How to set up GPG commit signing on Mac

Dec 10, 2025 | Security | 0 comments

Following the recent Shai Hulud supply-chain incident, development teams are prioritizing stronger safeguards to protect their GitHub environments and maintain the integrity of their codebases. One effective measure to enhance authenticity and accountability in source control is signing Git commits with a GPG key. GPG signatures verify that each commit genuinely originates from its author—an important step in reinforcing trust across collaborative and open-source projects. By configuring your GitHub account to use commit signing and enabling vigilant mode, you can significantly strengthen the security and credibility of your contributions.

Here are the steps on how you can set up GPG commit on Mac computers:

Step 1. Install required packages

brew install gnupg pinentry-mac

  • gnupg is used to manage the keys
  • pinentry is used to safely store the gpg passphrase inside the osx keychain so you don’t have to provide the passphrase every time you create a commit. Remember that the GPG private key generated during this process should remain securely stored on your personal device and never be shared.

Step 2. Configure gpg agent and the cache time for the passphrase

  1. Check that ~/.gnupg/gpg-agent.conf exists otherwise create the file using the command touch ~/.gnupg/gpg-agent.conf.
  2. Run echo "pinentry-program $(which pinentry-mac)" >> ~/.gnupg/gpg-agent.conf to append the pinentry-progam path.
  3. Open ~/.gnupg/gpa-agent.conf with any text editor. Add cache time that in number of seconds.
    For example, mine is currently set to 8 hours, so I have to provide my passphrase every 8 hours.
    • default-cache-ttl 28800
    • max-cache-ttl 28800
  4. Restart the gpg agent gpgconf --kill gpg-agent

Step 3. Generate your key

Once our packages are installed we are ready to generate our key. Open a terminal and run

gpg --full-generate-key

  • Use RSA
  • Select type 4096 when asked for the bits
  • Enter your email address.
  • The comment is optional but useful if you have multiple keys

Step 4. Add the key to GitHub

You can list all your keys to grab the ID by using the following command in your terminal:

gpg --list-secret-keys --keyid-format=long

We will need to use the key id to retrieve the public key that is required by GitHub. The key id is the value on the first line starting by sec after the encryption algorithm

You’ll see something like this:

sec   rsa4096/ABC123456789DEF0 2024-11-26 [SC]

The ABC123456789DEF0 part is your GPG key ID.

Copy your key id and let’s use it to get our public key

gpg --armor --export ABC123456789DEF0

If you’re using a Git hosting service like GitHub, GitLab, or Bitbucket, you’ll want to add your GPG public key to your account so that the platform can verify your signed commits.

Step 5. Add the Key to Your Git Hosting Service

Head over to your GitHub settings(this link is a shortcut) to add your key. Paste the whole public key we got from the previous command.

Once added, the key should be visible under your settings, don’t forget to enable the vigilant mode.

Step 6. Enabling commit and release signing by default

It’s time to tweak our git configuration to make sure that all commits and release tagging are signed.

git config --global commit.gpgsign true

git config --global tag.gpgSign true

Enable auto-signing for all commits:

git config --global commit.gpgsign true

We need to tell git which gpg key to use. You’ll need your key id for that.

git config --global user.signingkey 174CFC98A8FEC98E

  1. Tell Git to use this key:
git config --global user.signingkey ABC123456789DEF0

Step 7. Signing our first commit

Let’s initialize an empty git repository locally.

mkdir random-name cd random-name git init

No need to create new files, we can commit an empty change in our case.

git commit -m "my first signed commit" --allow-empty

Once done, we can verify that everything worked and you should be able to see that the commit has been correctly signed.

git log --show-signature

Step 8. IDE configuration

For Intellij, it should be automatic. You can check the settings under version control. You should see Commits are signed …

468