1) Install GPG on macOS

The cleanest way is Homebrew:

brew install gnupg

That installs GnuPG and gives you the gpg command on macOS.

You can verify it worked with:

gpg --version

There is also a macOS installer route listed by GnuPG, but for developer use on macOS, Homebrew is usually the least painful option.

2) Create a GPG key

GitLab’s current docs say to generate a key with either gpg --gen-key or, on newer GPG versions, gpg --full-gen-key. They recommend RSA and RSA with 4096 bits.

Run:

gpg --full-gen-key

Pick:

  • key type: RSA and RSA
  • key size: 4096
  • expiration: your call; no expiration is allowed
  • name: your name
  • email: the same email you use in GitLab
  • passphrase: set one

Important: the email you enter here must match a verified email in your GitLab account, or GitLab won’t verify the signature properly.

3) Get your key ID

List your secret keys:

gpg --list-secret-keys --keyid-format LONG you@example.com

You’ll see output like:

sec   rsa4096/30F2B65B9246B6CA 2026-03-18 [SC]

The part after the slash is your key ID:

30F2B65B9246B6CA

That’s the value you need for Git.

4) Export your public key

gpg --armor --export 30F2B65B9246B6CA

Copy the full block, including:

-----BEGIN PGP PUBLIC KEY BLOCK-----
...
-----END PGP PUBLIC KEY BLOCK-----

That is what you add to GitLab.

5) Add the public key to your self-hosted GitLab

In GitLab:

  • click your avatar
  • go to Edit profile
  • go to Access > GPG keys
  • click Add new key
  • paste the armored public key
  • save

GitLab then stores the key fingerprint, email, and creation date.

6) Tell Git to use that key

Set your signing key globally:

git config --global user.signingkey 30F2B65B9246B6CA

Then make Git sign all commits by default:

git config --global commit.gpgsign true

GitLab documents both of those steps directly.

Also make sure your Git identity matches the GitLab account/email you expect:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

7) Make a signed commit

git commit -S -m "Test signed commit"

Or, since you enabled signing by default, normal commits should also be signed:

git commit -m "Test signed commit"

Push it, then open the commit in GitLab. A valid match should show a Verified badge.

8) macOS fix for passphrase / pinentry issues

For zsh on macOS:

echo 'export GPG_TTY=$(tty)' >> ~/.zshrc
source ~/.zshrc

That fixes a lot of “signing failed” nonsense.