Appearance

Powered by Platform One

Configure Commit Signing on Mac with GPG ​

Overview ​

This article explains how to configure your Mac to sign Git commits with a GPG key.

All commits must be signed using either a CAC or a GPG key. Developers who do not use a CAC can configure Git to sign commits using a GPG key.

For projects operating in IL4 and IL5 environments, CAC signing is required. If you have a CAC, follow the Configure Commit Signing on Mac with Your CAC Guide instead.

WARNING

Store your GPG private key securely. Anyone with access to your private key can create signed commits that appear to come from you.

WARNING

Party Bus does not support commit signing through IDE integrations. If you create commits in an IDE, use the command line to sign them. Do not submit Party Bus support requests for IDE-specific commit signing issues.

Prerequisites ​

Before you begin:

  1. Install Git.

  2. Install Homebrew, if it is not already installed.

  3. Install GnuPG.

    bash
    brew install gpg

  4. Verify the installation.

    bash
    gpg --version
git --version

Generate a GPG Key ​

  1. Generate a new GPG key.

    bash
    gpg --full-gen-key

  2. When prompted:

  • Select RSA and RSA when prompted for the key type.
  • Choose an appropriate key size (4096 bits recommended).
  • Specify an expiration date if required.
  • Enter your name and Git email address.
  • Protect the key with a strong passphrase.

Identify Your GPG Signing Key ​

  1. List your secret keys.

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

    Example:

    text
    rsa4096/3AA5C34371567BD2 2026-07-10 [SC]

    Record the long key ID (3AA5C34371567BD2). You'll use this value when configuring Git.

Add Your Public GPG Key to GitLab ​

  1. Export your public key.

    bash
    gpg --armor --export <KEY_ID>

  2. Copy the entire output, including:

    text
    -----BEGIN PGP PUBLIC KEY BLOCK-----

 ...

-----END PGP PUBLIC KEY BLOCK-----

  3. In GitLab, open User Settings > GPG Keys.

  4. Paste the public key and select Add key.

  5. Confirm the key status shows as Verified in GitLab.

Configure Git ​

Configure Git to sign commits using your GPG key.

  1. Configure your Git identity.

    bash
    git config --global user.email "<GITLAB_EMAIL_ADDRESS>"
git config --global user.name "<FIRSTNAME LASTNAME>"

    Ensure this email address matches a verified email address on your GitLab account. Otherwise, GitLab cannot verify your signed commits.

  2. Configure Git for commit signing.

    bash
    git config --global user.signingkey <KEY_ID>
git config --global commit.gpgsign true

  3. Verify the configuration.

    bash
    git config --list | grep -E "user|gpg|commit"

    Confirm the output includes:

    • Your GitLab email address.
    • Your GPG signing key.
    • true for commit.gpgsign.

Configure Pinentry ​

Configure pinentry-mac so macOS can prompt for your GPG passphrase when signing commits.

  1. Install pinentry-mac.

    bash
    brew install pinentry-mac

  2. Configure GPG to use pinentry-mac.

    bash
    echo "pinentry-program $(which pinentry-mac)" >> ~/.gnupg/gpg-agent.conf

  3. Configure the GPG terminal environment variable for zsh.

    bash
    echo "export GPG_TTY=\$(tty)" >> ~/.zshrc
source ~/.zshrc

  4. Restart the GPG agent.

    bash
    gpgconf --kill gpg-agent

Verify Commit Signing ​

  1. Create a test commit.

    bash
    git commit --allow-empty -m "test commit signing"

  2. Enter your GPG passphrase when prompted.

  3. Verify the commit signature.

    bash
    git log --show-signature -1

    The commit should appear as Verified in GitLab.

Optional: Configure VS Code Commit Signing ​

If you choose to sign commits from VS Code:

  1. Open VS Code Settings (cmd+ or Preferences > Settings).

  2. Search for Git: Enable Commit Signing and enable the setting.

VS Code will use your existing GPG configuration when creating signed commits.

Troubleshooting ​

GPG fails to sign the commit ​

If Git returns:

text
error: gpg failed to sign the data
fatal: failed to write commit object

Run:

bash
echo "test" | gpg --clear-sign

If signing succeeds, GPG is functioning correctly.

If you receive a timeout error, restart the GPG agent:

bash
gpgconf --kill gpg-agent

Then retry the commit.

Git cannot find the signing key ​

If Git returns:

text
could not find identity matching specified user-id
error: gpg failed to sign the data
fatal: failed to write commit object

Verify that gpg.format is not configured.

bash
git config --get gpg.format

If a value is returned, remove it.

bash
git config --unset gpg.format

If the setting persists, remove the gpg.format entry manually from your ~/.gitconfig file, then retry the commit.

Enable Git trace logging ​

For additional troubleshooting, enable Git trace output.

bash
GIT_TRACE=1 git commit -S -m "test commit"

Related Content/References ​

Submit Requests to the Help Desk ​

Install Required Software ​

Review Supporting Documentation ​

Powered By Platform One