Introducing Vouch Git Workflow

Supply chain attacks are on the rise. In 2024 alone, we saw major incidents affecting millions of developers through compromised dependencies and malicious commits. The solution? Cryptographically sign every commit to prove it came from you.

With Vouch Protocol, you can set this up in under 60 seconds.

What You'll Achieve

• Every git commit signed with your cryptographic identity
• GitHub shows the "Verified" badge on your commits
• Zero manual signing—it just works automatically
• Use your existing SSH key (no new keys to manage)

Prerequisites

• Python 3.8+ installed
• Git configured with your name and email
• An SSH key added to your GitHub account (optional - Vouch will generate one if you don't have it)

Quick Start (30 seconds)

pip install vouch-protocol

vouch git init

Verify It Works

# Make a test commit
git commit --allow-empty -m "test: verify vouch signing"

# Check on GitHub - you'll see the Verified badge!

Why Vouch vs. Other Signing Methods

There are several ways to sign Git commits. Here's how they compare:

Bottom line: GPG requires managing keyrings, expiration dates, and subkeys. Manual SSH setup requires multiple git config commands and a trip to GitHub settings. Vouch handles everything in one command.

How It Works

Vouch leverages SSH signing (introduced in Git 2.34+). When you run vouch git init, it:

1. Generates a new Ed25519 signing key (or uses your existing one at ~/.ssh/id_ed25519)
2. Uploads the key to GitHub as a signing key (via gh CLI)
3. Configures Git to sign all commits:

   git config --global gpg.format ssh
   git config --global user.signingkey ~/.vouch/keys/vouch_signing_key
   git config --global commit.gpgsign true

4. Sets up local verification with an allowed signers file

GitHub Integration (Automatic!)

vouch git init automatically uploads your signing key to GitHub using the GitHub CLI. You don't need to do anything manually!

After running the command, you'll see:

 Uploading signing key to GitHub...
   SSH key uploaded to GitHub!

That's it! Push a commit and you'll see the Verified badge immediately.

Manual Configuration (Alternative)

If you prefer to configure git manually without the CLI:

# Use SSH for signing
git config --global gpg.format ssh

# Set your signing key
git config --global user.signingkey ~/.ssh/id_ed25519.pub

# Auto-sign all commits
git config --global commit.gpgsign true

# Auto-sign all tags
git config --global tag.gpgsign true

Troubleshooting

Commit fails with "error: Load key failed"

Your SSH key might require a passphrase. Add it to your SSH agent:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

GitHub doesn't show "Verified"

This usually means the gh CLI upload failed silently. Check if your key is on GitHub:

gh ssh-key list

If not listed, re-run vouch git init or manually add the key at GitHub Settings → SSH Keys.

Check your current git signing config

git config --global --list | grep -E "(gpg|sign)"

How Others Verify Your Commits

When you sign commits, here's how collaborators and reviewers can verify they're genuinely from you:

1. GitHub's Verified Badge (Automatic)

When you push signed commits to GitHub:

• GitHub checks if the signing key matches a key registered to your account
• If it matches → Verified badge appears on the commit
• Click the badge to see: "This commit was signed with the committer's verified signature"

2. Verify Anyone's Public Key

Anyone can check a GitHub user's public SSH keys at:

https://github.com/<username>.keys

Compare this with the key fingerprint shown in the commit signature to confirm authenticity.

3. Local Verification

To verify signatures locally:

# View signature details
git log --show-signature -1 <commit-hash>

# Verify a specific commit
git verify-commit <commit-hash>

For Teams & Organizations

Adopting signed commits across your team provides:

• Supply Chain Security: Every commit is cryptographically tied to a verified developer
• Audit Trail: Immutable proof of who authored each change
• Compliance: Meet SOC2, ISO 27001, and other security standards requiring code provenance
• Trust: Reviewers can verify PRs come from legitimate team members

Enforce Signed Commits (GitHub)

1. Go to Repository Settings → Branches
2. Add a branch protection rule for main
3. Enable "Require signed commits"

Now all commits to protected branches must be signed!

Why This Matters

Recent supply chain attacks highlight why commit signing is critical:

• SolarWinds (2020): Attackers injected malicious code into build pipelines
• Codecov (2021): Compromised CI scripts exfiltrated credentials
• XZ Utils (2024): Maintainer impersonation led to backdoored releases

Signed commits create a chain of custody. If every commit is signed, attackers can't inject code without either stealing a developer's private key or creating obviously unsigned commits.

What's Next?

• Try the Demo - See signature verification in action
• Star us on GitHub - Help spread the word
• Read the Technical Digest - Deep dive into the protocol
• Join our Discord - Get help and share feedback