GPG

This setup is for MacOS users. If you’re on Linux, you likely have GPG already installed, and the steps are similar but may differ in details.

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.