Signed Commits — The Fake Commit That Almost Deployed Malware

Git commits have an author field that can be set to ANY name and email. git config user.name 'Linus Torvalds' && git config user.email 'torvalds@linux.com' — there's no authentication. This is a feature (Git is trust-based) but also a vulnerability. A malicious actor with push access can impersonate anyone. GPG signing solves this by attaching a cryptographic signature that GitHub/GitLab verifies against your public key. This guide covers setup, the incident where unsigned commits almost deployed malware, and how to enforce signing in your CI/CD pipeline.

Why GPG Signing Matters in Production

In a collaborative codebase, every commit carries the author's name and email. But Git allows anyone to claim any identity. Without cryptographic verification, a malicious actor can impersonate a trusted developer and introduce backdoors. GPG signing binds each commit to a specific key, ensuring authenticity and non-repudiation. In production environments, this is not optional—it's a compliance requirement for SOC 2, PCI-DSS, and FedRAMP. I've seen teams waste days auditing commits after a breach because they couldn't prove who pushed what. GPG signing eliminates that ambiguity. It also enables tools like GitHub's 'Verified' badge, which signals to CI/CD pipelines that the commit is trustworthy. If your pipeline blindly trusts unsigned commits, you're one compromised credential away from a supply chain attack.

#!/bin/bash
# Check if GPG signing is configured globally
git config --global user.signingkey || echo "No signing key set"
git config --global commit.gpgsign || echo "Commit signing not enabled"
# Verify a signed commit
git log --show-signature -1

Generating a GPG Key Pair

Before signing commits, you need a GPG key pair. Use gpg --full-generate-key for a production-grade key. Choose RSA with 4096 bits—anything less is insecure. Set an expiration date (e.g., 1 year) to enforce rotation. Use a strong passphrase; store it in a password manager, not in plaintext. The key's email must match the email you use in Git commits. If you have multiple emails, create separate keys or add UIDs. After generation, export the public key: gpg --armor --export <key-id>. Upload this to GitHub/GitLab under Settings > SSH and GPG keys. Never share your private key. For teams, consider using a hardware security key (e.g., YubiKey) to store the private key—this prevents exfiltration even if your machine is compromised.

gpg --full-generate-key
# Interactive prompts:
# Kind of key: (1) RSA and RSA
# Keysize: 4096
# Expiration: 1y
# Real name: Jane Doe
# Email: jane@example.com
# Passphrase: <secure passphrase>

# List keys to get key ID
gpg --list-secret-keys --keyid-format LONG

Configuring Git to Sign Commits

Once you have a GPG key, tell Git to use it. Set user.signingkey to your key ID. Enable automatic signing with commit.gpgsign = true. For tag signing, set tag.gpgsign = true. If you use multiple machines, replicate this config on each. Use --global for system-wide settings, or per-repo if you have different keys for work and personal projects. Verify with git config --list | grep gpg. On macOS, you may need to install pinentry-mac for passphrase prompts. On Linux, pinentry-gtk or pinentry-tty works. If you use a smartcard, configure gpg-agent to cache the passphrase for a session. Without caching, you'll be prompted for every commit—annoying but secure.

#!/bin/bash
# Set signing key (replace with your key ID)
git config --global user.signingkey 1A2B3C4D5E6F7G8H
# Enable automatic commit signing
git config --global commit.gpgsign true
# Enable tag signing
git config --global tag.gpgsign true
# Verify configuration
git config --global --list | grep gpg

Signing Commits and Tags

With Git configured, every commit is automatically signed. You can also sign manually with git commit -S. For tags, use git tag -s. The -s flag signs the tag. To verify a signed commit, use git log --show-signature. This displays the GPG signature status. If the key is trusted, you'll see 'Good signature'. If not, 'Can't check signature: public key not found'. Always import the signer's public key to verify. For batch verification, use git verify-commit HEAD or git verify-tag v1.0. In a team, enforce signing with server-side hooks or branch protection rules. GitHub and GitLab can require signed commits on protected branches. This prevents unsigned commits from being merged.

#!/bin/bash
# Create a signed commit (automatic if configured)
git commit -m "Fix critical bug in auth module"
# Or explicitly sign
git commit -S -m "Fix critical bug in auth module"
# Sign a tag
git tag -s v1.0 -m "Release v1.0"
# Verify commit signature
git log --show-signature -1

Managing Multiple GPG Keys

Developers often have multiple identities: work, personal, open-source. You can manage multiple GPG keys by associating each with a different Git email. Use gpg --list-secret-keys to see all keys. For each repo, set user.email and user.signingkey locally (without --global). Alternatively, use Git's includeIf directive in ~/.gitconfig to conditionally load config based on directory. For example, all repos under ~/work/ use the work key. This avoids manual per-repo setup. When rotating keys, add the new key to your GitHub account and keep the old one until all commits are re-signed. Revoke old keys with gpg --revoke-key. Notify your team to import the new public key.

# ~/.gitconfig
[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work

# ~/.gitconfig-work
[user]
    name = Jane Doe
    email = jane@company.com
    signingkey = 1A2B3C4D5E6F7G8H
[commit]
    gpgsign = true

# For personal projects, global config applies
[user]
    name = Jane Doe
    email = jane@personal.com
    signingkey = 9H8G7F6E5D4C3B2A
[commit]
    gpgsign = true

Enforcing Signed Commits in CI/CD

Server-side enforcement is critical. On GitHub, enable 'Require signed commits' on protected branches. GitLab has similar settings. For self-hosted Git servers, use a pre-receive hook that rejects unsigned commits. The hook checks git log --show-signature and exits non-zero if the signature is missing or invalid. You can also verify that the commit was signed by a key in an allowed list. This prevents even administrators from bypassing signing. In CI pipelines, use git verify-commit to check the latest commit before building. If verification fails, fail the pipeline. This ensures that only verified code reaches production. For extra security, use a hardware key for the CI signing key and store it in a secure vault.

#!/bin/bash
# Pre-receive hook to reject unsigned commits
while read oldrev newrev refname; do
    if [ "$refname" = "refs/heads/main" ]; then
        for commit in $(git rev-list $oldrev..$newrev); do
            if ! git verify-commit $commit &>/dev/null; then
                echo "ERROR: Commit $commit is not signed or signature invalid"
                exit 1
            fi
        done
    fi
done
exit 0

Troubleshooting Common GPG Issues

Common issues: 'secret key not available' means the private key isn't in the keyring. Import it with gpg --import private.key. 'Can't check signature: public key not found' means the verifier lacks the public key. Share your public key via keyserver or upload to GitHub. 'gpg: signing failed: No pinentry' indicates missing pinentry program. Install pinentry-mac or pinentry-tty. 'gpg: signing failed: Operation cancelled' often means the passphrase dialog timed out. Increase cache TTL in gpg-agent.conf. If commits show 'Good signature' but GitHub shows 'Unverified', ensure the commit email matches the key's UID email exactly. Also, the key must be uploaded to GitHub. For Windows, use Gpg4win and configure Git to use its GPG binary.

#!/bin/bash
# Check if GPG agent is running
gpg-agent --daemon
# List secret keys
gpg --list-secret-keys
# Import a private key
gpg --import ~/backup/private.key
# Export public key for GitHub
gpg --armor --export 1A2B3C4D5E6F7G8H > public.asc
# Test signing
echo "test" | gpg --clearsign

Revoking and Rotating GPG Keys

Keys expire or get compromised. Generate a revocation certificate immediately after creating a key: gpg --gen-revoke <key-id>. Store it offline. To revoke, import the certificate: gpg --import revoke.asc. Then upload the revoked public key to keyservers and GitHub. For rotation, create a new key, add it to GitHub, and update Git config. Old commits remain signed with the old key—they'll show as 'Verified' if the key hasn't been revoked. If the old key is compromised, revoke it and re-sign all commits with the new key using git filter-repo or git rebase. This rewrites history, so coordinate with your team. After rotation, delete the old private key securely: gpg --delete-secret-key <key-id>.

#!/bin/bash
# Generate revocation certificate
gpg --gen-revoke 1A2B3C4D5E6F7G8H > revoke.asc
# Revoke the key
gpg --import revoke.asc
# Upload to keyserver
gpg --keyserver keyserver.ubuntu.com --send-keys 1A2B3C4D5E6F7G8H
# Delete secret key
gpg --delete-secret-key 1A2B3C4D5E6F7G8H

Integrating GPG with Git Hosting Platforms

GitHub, GitLab, and Bitbucket all support GPG verification. Upload your public key in user settings. For organizations, you can require members to have verified keys. GitHub shows a 'Verified' badge next to signed commits. GitLab shows 'Verified' in the commit details. Bitbucket supports GPG but requires server-side hooks for enforcement. For self-hosted GitLab, enable 'Require GPG signatures' in project settings. For Gitea, install a plugin. If you use multiple platforms, upload the same public key to each. Some platforms also support SSH signing as an alternative, but GPG is more widely adopted. Ensure your CI system's signing key is also uploaded to the platform so that CI-generated commits show as verified.

#!/bin/bash
# Export public key in ASCII armor
gpg --armor --export 1A2B3C4D5E6F7G8H > public.asc
# Copy the output and paste into GitHub/GitLab settings
cat public.asc

Auditing Signed Commits in Production

Regular audits ensure signing compliance. Use git log --show-signature to review all commits in a release. Automate this with a script that fails if any commit is unsigned or signed by an untrusted key. For compliance, export the audit log: git log --format='%H %aN <%aE> %G?' --show-signature. The %G? shows signature status: 'G' for good, 'B' for bad, 'U' for untrusted, 'N' for no signature. Parse this to generate reports. Store the audit logs in a secure, immutable bucket. In case of an incident, you can prove exactly who signed what. If a key is revoked, re-audit all commits signed with that key. Tools like git-evtag can verify signed tags in a reproducible way.

#!/bin/bash
# Audit all commits in the current branch
for commit in $(git rev-list HEAD); do
    sig=$(git verify-commit $commit 2>&1)
    if echo "$sig" | grep -q "Good signature"; then
        echo "OK: $commit"
    else
        echo "FAIL: $commit - $sig"
        exit 1
    fi
done
echo "All commits signed and verified."

Advanced: Signing with Hardware Security Keys

For maximum security, store your GPG private key on a hardware token like YubiKey or Nitrokey. This prevents key extraction even if your machine is compromised. Generate the key on the device using gpg --card-edit or generate offline and transfer. The key never leaves the token. Signing operations happen on the device. Configure gpg-agent to use the token. On macOS, install yubikey-personalization and gnupg. On Linux, install pcscd and scdaemon. Test with gpg --card-status. The token requires a PIN for each signing operation. This adds friction but is necessary for high-security environments. Some tokens support biometrics. Hardware keys are tamper-resistant and can be revoked by destroying the token.

#!/bin/bash
# Check if YubiKey is detected
gpg --card-status
# Generate key on YubiKey
gpg --card-edit
> admin
> generate
# Use existing key: gpg --edit-key <key-id> > keytocard
# Configure agent to use token
echo "use-agent" >> ~/.gnupg/gpg.conf
echo "pinentry-program /usr/bin/pinentry-gtk-2" >> ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent

Automating GPG Key Distribution

In a team, you need a way to distribute public keys. Use a keyserver like keyserver.ubuntu.com or host your own with Hockeypuck. Automate key import in CI: gpg --keyserver keyserver.ubuntu.com --recv-keys <key-id>. For air-gapped environments, distribute keys via a secure channel (e.g., encrypted email). Use a keys/ directory in your repository containing ASCII-armored public keys. In CI, import all keys: gpg --import keys/*.asc. Mark keys as ultimately trusted: echo <key-id>:6: | gpg --import-ownertrust. This prevents 'untrusted' warnings. For large teams, consider using a central key management system like Vault's PKI or a GPG key server with access control.

#!/bin/bash
# Import all public keys from a directory
for keyfile in keys/*.asc; do
    gpg --import "$keyfile"
done
# Trust all imported keys ultimately (use with caution)
gpg --list-keys --with-colons | grep ^pub | cut -d: -f5 | while read keyid; do
    echo "$keyid:6:" | gpg --import-ownertrust
done