GPG Signing

GPG signing provides cryptographic verification of commits, ensuring authenticity and non-repudiation for compliance-critical codebases.

Why Sign Commits?

Compliance Requirements

Many compliance frameworks require verified authorship:

FDA 21 CFR Part 11: Electronic signatures
SOC2: Access control verification
ISO 13485: Traceability requirements

Security Benefits

Authenticity: Proves who made the commit
Integrity: Detects tampering
Non-repudiation: Cannot deny authorship

Quick Setup

1. Check Existing Keys

sc gpg status

2. Generate a New Key

sc gpg setup

This interactively guides you through:

Key generation
Git configuration
GitHub/GitLab integration

3. Configure Signing

# Enable signing for all commits
git config --global commit.gpgsign true

# Set your signing key
git config --global user.signingkey YOUR_KEY_ID

Manual Setup

Generate GPG Key

# Generate a new key pair
gpg --full-generate-key

# Choose:
# - RSA and RSA (default)
# - 4096 bits
# - Key does not expire (or set expiration)
# - Your real name and email

Find Your Key ID

gpg --list-secret-keys --keyid-format=long

# Output shows:
# sec   rsa4096/XXXXXXXXXXXXXXXX 2024-01-01
#       XXXXXXXXXXXXXXXX is your key ID

Configure Git

# Set your signing key
git config --global user.signingkey XXXXXXXXXXXXXXXX

# Enable signing by default
git config --global commit.gpgsign true

# Configure GPG program (if needed)
git config --global gpg.program gpg

Export Public Key

# Export for GitHub/GitLab
gpg --armor --export your.email@example.com

Copy the output and add to your Git hosting provider.

Platform Setup

GitHub

Go to Settings → SSH and GPG keys
Click "New GPG key"
Paste your public key
Save

GitLab

Go to User Settings → GPG Keys
Paste your public key
Click "Add key"

Bitbucket

Personal settings → GPG keys
Add key
Paste public key

Verification

Check Signed Commits

# Show signature info
git log --show-signature

# Verify specific commit
git verify-commit HEAD

GitHub Verified Badge

Signed commits show a "Verified" badge on GitHub when:

GPG key is added to your account
Email in key matches commit email
Key is not expired or revoked

Troubleshooting

"gpg failed to sign the data"

# Test GPG
echo "test" | gpg --clearsign

# If TTY issues
export GPG_TTY=$(tty)
echo 'export GPG_TTY=$(tty)' >> ~/.zshrc

"secret key not available"

# List available keys
gpg --list-secret-keys

# Check key ID in git config
git config user.signingkey

macOS: "Inappropriate ioctl for device"

# Install pinentry-mac
brew install pinentry-mac

# Configure GPG agent
echo "pinentry-program $(which pinentry-mac)" >> ~/.gnupg/gpg-agent.conf

# Restart agent
gpgconf --kill gpg-agent

Key Expired

# Edit key
gpg --edit-key YOUR_KEY_ID

# At gpg> prompt:
expire
# Set new expiration
save

CI/CD Integration

GitHub Actions

jobs:
  sign:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Import GPG key
        uses: crazy-max/ghaction-import-gpg@v6
        with:
          gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }}
          passphrase: ${{ secrets.GPG_PASSPHRASE }}
          git_user_signingkey: true
          git_commit_gpgsign: true

Environment Variables

# For automated signing
export GPG_TTY=$(tty)
export GNUPGHOME=/path/to/.gnupg

Best Practices

Use Strong Keys: 4096-bit RSA minimum
Set Expiration: 1-2 years, then rotate
Backup Keys: Store securely offline
Use Passphrases: Protect private key
Regular Rotation: Update keys periodically
Revocation Certificate: Generate and store safely

Supernal Coding Integration

Automatic Verification

# Check signing status
sc gpg status

# Verify all recent commits
sc gpg verify --commits=10

Compliance Reports

GPG signing information is included in compliance reports:

sc compliance report --include-signatures

Tools Reference

CLI Reference

CLI Reference

Dashboard

Git Hooks

GPG Signing