GPG Key

generate.md

Step by Step (macOS + Homebrew)

1. Install and Check dependencies

brew install gnupg pinentry-mac

2. Create directory and give permissions

export GNUPGHOME="$HOME/.gnupg"
mkdir -p "$GNUPGHOME"
chmod 700 "$GNUPGHOME"

3. Setup pinentry and GPG Agent

echo "pinentry-program $(brew --prefix)/bin/pinentry-mac" > "$GNUPGHOME/gpg-agent.conf"
# optional: performance and compatibility
cat <<'EOF' > "$GNUPGHOME/gpg.conf"
use-agent
personal-digest-preferences SHA512 SHA384 SHA256
cert-digest-algo SHA256
EOF

4. Restart agent and solve TTY/sockets

unset GPG_AGENT_INFO
gpgconf --kill gpg-agent
gpgconf --create-socketdir
export GPG_TTY=$(tty)
gpg-connect-agent updatestartuptty /bye
gpgconf --launch gpg-agent

5. Check if a secret key exists

gpg --list-secret-keys --keyid-format=long
# or for your specific key:
gpg --list-secret-keys --keyid-format=long <gpg_key_here>

If not listed, you must import or generate one.

• Import: gpg --import /path/to/your/secret-key.asc
• Generate: gpg --full-generate-key

6. Test it!

echo test | gpg --clearsign

⚠️ Must show the pinentry pop-up (or Touch ID) and create a signed block. It starts with: -----BEGIN PGP SIGNATURE-----

7. Point to track Git and test your commit again

git config --global gpg.program "$(which gpg)"
git config --global user.signingkey <your-key-here>
git config --global commit.gpgsign true
export GPG_TTY=$(tty)
git commit -m "[type]: <your commit message>"

If still fails

1. Force loopback (last resource / CI):

echo "allow-loopback-pinentry" >> "$GNUPGHOME/gpg-agent.conf"
gpgconf --kill gpg-agent && gpgconf --launch gpg-agent
git config --global gpg.program "gpg --pinentry-mode=loopback"
echo test | gpg --pinentry-mode=loopback --clearsign

2. Verify where GPG is tracking (homedir):

gpgconf --list-dirs | sed -n 's/^homedir:\(.*\)/GNUPGHOME=\1/p'

3. Test pinetry directly: $(brew --prefix)/bin/pinentry-mac

⚠️ If doesn't open, the path of gpg-agent.conf is incorrect.