Set Up Git and GPG Commit Signing

GPG (GNU Privacy Guard) uses public-key cryptography to sign and verify commits. When you sign a commit with your private key, anyone with your public key can verify that the commit was made by you and has not been tampered with. In GitLab, signed commits display a Verified badge next to the commit message, which provides:

• Authenticity — proof that the commit was made by the person who claims to have made it.
• Integrity — assurance that the commit content has not been altered after signing.
• Accountability — a verifiable chain of authorship for compliance and audit purposes.

Homebrew is a package manager for macOS. If you do not have administrative access, you can install it locally:

cd ~
mkdir -p ~/homebrew && curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C homebrew

Add Homebrew to your shell PATH by adding this line to your .bash_profile or .zshrc, then restart your terminal (or run source ~/.zshrc):

export PATH=$HOME/homebrew/bin:$PATH

Windows — You do not need Homebrew. Install Git and GnuPG with your preferred package manager (for example, Git for Windows and Gpg4win), then continue with the GPG key generation steps below.

On macOS, install GnuPG using Homebrew:

brew install gnupg

If this is the first Homebrew package you install, Homebrew may run an initial update that takes several minutes.

Windows — Install GnuPG as part of Gpg4win or via your existing package manager, then ensure gpg is available in your %PATH% (for example, from a Git Bash or PowerShell session).

On macOS, install the graphical pinentry helper so GPG can prompt for your passphrase in a native dialog:

brew install pinentry-mac

On most setups GnuPG uses pinentry-mac automatically once it is installed. If you hit passphrase-prompt issues, see Troubleshooting.

Add the following to your .bash_profile or .zshrc so GPG can prompt for your passphrase correctly in the terminal:

export GPG_TTY=$(tty)

Windows — If you use Git Bash or WSL, add the same export GPG_TTY=$(tty) line to your shell profile. If you primarily use PowerShell or CMD, Gpg4win's default configuration usually handles passphrase prompts without this setting.

Run the key generation command and follow the prompts:

gpg --full-generate-key

Use these settings:

You will be prompted to create a passphrase. Choose a strong passphrase and store it securely.

List your secret keys to find the key ID:

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

The output looks similar to:

sec   rsa3072/ABC123DEF456 2025-01-01
      ABCDEF1234567890ABCDEF1234567890ABC123DE
uid           [ultimate] Jane Smith <jane.smith@example.org>

The key ID is the value after rsa3072/ — in this example, ABC123DEF456. The second line is the full fingerprint. Git accepts either the key ID or the full fingerprint as user.signingkey.

Export your public key in ASCII-armored format, replacing ABC123DEF456 with your actual key ID:

gpg --armor --export ABC123DEF456

Copy the entire output, including the -----BEGIN PGP PUBLIC KEY BLOCK----- and -----END PGP PUBLIC KEY BLOCK----- lines.

1. Log in to IronSled GitLab.
2. Navigate to Profile → Preferences → GPG Keys (or Edit Profile → GPG Keys).
3. Paste your exported public key into the text box.
4. Click Add Key.

GitLab verifies the key and associates it with your account. From this point forward, any commit signed with this key displays a Verified badge.

Tell Git to use your GPG key for signing. You can use either the key ID or the full fingerprint from Step 5:

git config --global user.signingkey ABC123DEF456

Enable automatic signing on all commits so you do not need to remember the -S flag:

git config --global commit.gpgSign true

With automatic signing enabled, every git commit is signed. Without it, you must explicitly sign each commit:

git commit -S -m "Your commit message"

Automatic signing is recommended — it prevents accidentally pushing unsigned commits that branch protection would reject. A typical global Git configuration looks like this:

[user]
  name = user.name
  email = user.name@example.org
  signingkey = ABC123DEF456

[commit]
  gpgsign = true

[gpg]
  program = /opt/homebrew/bin/gpg

macOS — The gpg.program path above (/opt/homebrew/bin/gpg) assumes GnuPG was installed with Homebrew on Apple Silicon. On Intel Macs it is usually /usr/local/bin/gpg.

Windows — You typically do not need a [gpg] program entry if Gpg4win or Git for Windows installed gpg onto your %PATH%. You can still set user.signingkey and commit.gpgSign with the same commands shown above.

Create a test commit and verify the signature:

git commit --allow-empty -S -m "test: verify GPG signing"
git log --show-signature -1

You should see Good signature from "Your Name <your.email@example.org>" in the output.

Visual Studio Code uses your system Git configuration, so if you set commit.gpgSign = true globally, commits made from VS Code are signed automatically — no extra configuration is needed. If you encounter passphrase-prompt issues, make sure GPG_TTY is set in your shell profile and that VS Code is launched from the terminal (or that its integrated terminal inherits your environment).

error: gpg failed to sign the data

• Ensure GPG_TTY is exported in your shell profile.
• Verify the GPG agent is running: gpg-connect-agent /bye
• Restart the agent: gpgconf --kill gpg-agent && gpg-connect-agent /bye

Commit rejected: unsigned commit

• Ensure commit.gpgSign = true is set globally, or use the -S flag.
• Verify your key ID is correct: git config --global user.signingkey

Key does not match any email on your GitLab account

• The email in your GPG key must exactly match the email on your GitLab profile.
• Check your key's email: gpg --list-keys --keyid-format LONG

Passphrase prompt not appearing

• On macOS, install pinentry-mac (see Step 2b) and, if needed, configure it:

  echo "pinentry-program /opt/homebrew/bin/pinentry-mac" >> ~/.gnupg/gpg-agent.conf
  gpgconf --kill gpg-agent && gpg-connect-agent /bye

• On Windows, ensure Gpg4win is installed with its pinentry component enabled, then restart your terminal or IDE.

If you need different GPG keys or identities for different repositories (for example, work versus personal), set a per-repository signing key from inside that repository with the --local flag, which overrides the global setting for that repo only:

git config --local user.signingkey <other-key-id>
git config --local user.email <matching-email>