guicedee/git-commit-signing

Git Commit Signing

Set up and manage cryptographic commit signing with the right identity for every repository.

Quick Start

1. Detect context — determine the repository remote, associated identity, and preferred signing method.
2. Configure identity — set user.name and user.email at the repo level (not global) to avoid cross-contamination.
3. Configure signing — choose GPG, SSH, or S/MIME and point git at the correct key.
4. Verify — make a test signed commit or tag and confirm it verifies cleanly.

Workflow

1) Identify the repository context

# Show current repo remote + identity
git remote -v
git config user.name
git config user.email
git config commit.gpgsign
git config gpg.format

Determine from the remote URL whether this is a personal, work, or open-source project and select the matching identity.

2) Configure user identity (per-repo)

Always set identity at the local (repo) level to prevent leaking the wrong email:

git config --local user.name  "Your Name"
git config --local user.email "[email protected]"

3) Enable commit signing

Option A — GPG signing (default, widest platform support)

# List available GPG keys
gpg --list-secret-keys --keyid-format=long

# Configure git to use GPG
git config --local gpg.format openpgp
git config --local user.signingkey <KEY-ID>
git config --local commit.gpgsign true
git config --local tag.gpgsign true

# (Optional) tell git where gpg lives
git config --local gpg.program "gpg"          # Linux/macOS
git config --local gpg.program "gpg.exe"      # Windows — or full path

Option B — SSH signing (simple, no extra tooling if you already use SSH keys)

# List available SSH keys
ls -la ~/.ssh/*.pub

# Configure git to use SSH signing
git config --local gpg.format ssh
git config --local user.signingkey ~/.ssh/id_ed25519.pub   # path to your PUBLIC key
git config --local commit.gpgsign true
git config --local tag.gpgsign true

# (Recommended) set allowed-signers for local verification
echo "[email protected] $(cat ~/.ssh/id_ed25519.pub)" >> ~/.config/git/allowed_signers
git config --local gpg.ssh.allowedSignersFile ~/.config/git/allowed_signers

Option C — S/MIME signing (corporate PKI environments)

git config --local gpg.format x509
git config --local user.signingkey <CERTIFICATE-ID>
git config --local commit.gpgsign true
git config --local tag.gpgsign true

4) Verify the configuration

# Create a signed test commit
echo "test" >> .git/signing-test && git add .git/signing-test
git commit --allow-empty -S -m "chore: test commit signing"

# Verify the signature
git log --show-signature -1

# Clean up
git reset --soft HEAD~1

5) Multi-identity management with includeIf

For developers who contribute to many repos under different identities, use conditional includes in ~/.gitconfig:

# ~/.gitconfig  (global)
[user]
    name = Default Name
    email = [email protected]

# Work repos live under ~/work/
[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work

# Personal repos live under ~/personal/
[includeIf "gitdir:~/personal/"]
    path = ~/.gitconfig-personal

# ~/.gitconfig-work
[user]
    name = Work Name
    email = [email protected]
    signingkey = <WORK-KEY-ID>
[commit]
    gpgsign = true
[gpg]
    format = openpgp

# ~/.gitconfig-personal
[user]
    name = Personal Name
    email = [email protected]
    signingkey = ~/.ssh/id_ed25519.pub
[commit]
    gpgsign = true
[gpg]
    format = ssh

Guardrails

• Never set signing identity globally unless you only have one identity — prefer --local or includeIf.
• Never commit a private key — signing keys reference public key paths (SSH) or key IDs (GPG/S/MIME).
• Pin the GPG/SSH program path on Windows to avoid PATH issues (gpg.program / gpg.ssh.program).
• Test after setup — always verify with git log --show-signature -1.
• Register your public key with your forge (GitHub → Settings → SSH and GPG keys, GitLab → User Settings → GPG/SSH Keys).

Scripts

Configure signing for the current repo interactively:

bash scripts/configure_signing.sh

PowerShell equivalent for Windows:

pwsh scripts/configure_signing.ps1

Verify that the current repo's signing is working:

bash scripts/verify_signing.sh

References

• Signing methods comparison and troubleshooting: references/signing-methods.md