GPG Signing

What it does

gitswitch automatically switches your GPG signing key when you change identities.

gitswitch work
# Now commits signed with gpg are signed by your work key

Why you need this

If you sign commits with GPG (commit signing is recommended for security), each identity might use a different key:

• Work identity signs with your corporate GPG key
• Personal identity signs with your personal GPG key
• Different keys may be registered with different GitHub accounts

Forgetting to update the signing key means:

• Unsigned commits attributed to the wrong identity
• Verification failures
• Trust issues on public repos

gitswitch handles it automatically.

Setup

Add profile with GPG key

gitswitch add work "Alice" alice@company.com \
  --gpg-key 1234567890ABCDEF

The GPG key ID should match a key in your keyring:

# List your GPG keys
gpg --list-secret-keys --keyid-format LONG

# Output:
# sec   rsa4096/1234567890ABCDEF 2023-01-15 [SC]
#       1234567890ABCDEF1234567890ABCDEF12345678

Use the 16-character ID after the /.

Generate GPG keys (if needed)

gpg --gen-key
# Follow the prompts to create a new key

gpg --list-secret-keys --keyid-format LONG
# Find your new key ID

How it works

When you switch profiles with a GPG key, gitswitch sets:

git config --global user.signingkey KEYID

Git looks up this key in your keyring when signing commits.

Signing commits

After switching to a profile with a GPG key, sign commits:

git commit -S -m "Signed commit"

Or configure git to always sign:

git config --global commit.gpgsign true

Now every commit is signed automatically.

Verify signature

Check which key signed a commit:

git verify-commit COMMIT_SHA

Or see in log:

git log --show-signature

Multiple GPG keys

Setup multiple profiles with different keys:

# List your keys
gpg --list-secret-keys --keyid-format LONG

# Add profiles
gitswitch add personal "Alice" alice@gmail.com \
  --gpg-key PERSONAL_KEY_ID

gitswitch add work "Alice" alice@company.com \
  --gpg-key WORK_KEY_ID

When you switch, the signing key switches too.

Troubleshooting

Key not found

error: key "KEYID" does not contain a secret key

Check:

1. Is the key ID correct?
2. Is the key in your keyring?

# List available keys
gpg --list-secret-keys --keyid-format LONG

# Add to keyring if needed
gpg --import ~/path/to/key.gpg

GPG hanging/asking for passphrase

If GPG hangs or asks for passphrase every time:

1. Use gpg-agent to cache passphrases:

# Edit ~/.gnupg/gpg-agent.conf
default-cache-ttl 3600
max-cache-ttl 7200

2. Restart gpg-agent:

gpgconf --kill gpg-agent

Verification fails on GitHub

GitHub only recognizes GPG keys that are:

1. Added to your GitHub account
2. Email-associated with a GitHub account

Check:

1. Go to https://github.com/settings/keys
2. Verify your GPG key is listed
3. Verify the email matches your git config

Signing without gitswitch

If you set a per-repo signing key:

cd ~/special-repo
git config --local user.signingkey SPECIAL_KEY_ID

Local config takes priority over global.

Next steps

→ GitHub Account Sync
→ Identity Awareness
→ SSH Key Management