Decoding 'Unverified' PGP Commits on GitHub: A Key Refresh Insight

GitHub's commit verification status is a crucial indicator of code integrity and author authenticity. When a PGP-signed commit unexpectedly shows "Unverified," it can raise concerns about security and developer workflow. A recent discussion in the GitHub Community sheds light on a common pitfall related to PGP key management and how GitHub interprets these keys.

The "Unverified" PGP Commit Conundrum

The discussion began with user ngie-eign reporting that their PGP-signed commits were incorrectly marked "Unverified" on GitHub. The core of the issue appeared when signing commits with an organization-specific email address (@FreeBSD.org) that differed from the primary email associated with their PGP key (@gmail.com). Despite the organization email being part of their PGP subkeys, GitHub's UI wasn't recognizing it, leading to persistent "Unverified" badges.

This scenario highlights a common source of confusion for developers leveraging PGP for commit signing. While the initial report framed it as a potential bug in GitHub's handling of subkeys, the community quickly provided a critical insight that often resolves such github alerts.

The Snapshot Effect: GitHub's GPG Key Management

The most valuable contribution came from hoangperry, who clarified a fundamental aspect of GitHub's GPG key management: GitHub does not automatically refresh uploaded GPG keys. Instead, it takes a snapshot of the key, including all its User IDs (UIDs), at the exact moment it is uploaded in your GitHub settings.

This means if you add a new email address (UID) to your PGP key *after* you've already uploaded that key to GitHub, GitHub's stored copy will not contain the new UID. Consequently, any commits signed with that newly added email address will appear "Unverified" because GitHub doesn't know that email is associated with your trusted key.

The Solution: Re-upload Your GPG Key

The fix for this common issue is straightforward:

1. Navigate to your GitHub Settings > SSH and GPG keys.
2. Delete the existing GPG key that is causing issues.
3. Re-add the current export of your PGP key. You can typically get this using:

   gpg --armor --export YOUR_KEY_ID

   (Replace YOUR_KEY_ID with your actual GPG key ID).

Once the updated key with all its UIDs is re-uploaded, existing commits signed with those UIDs should retroactively flip to "Verified" status. This simple step ensures that GitHub's internal records align with your current PGP key configuration, improving the accuracy of your git reporting tool data regarding commit authenticity.

Key Conditions for Verified Commits

Beyond re-uploading your key, hoangperry also emphasized two other crucial conditions for successful commit verification:

• Email Verification: The email address used for authoring the commit (e.g., @FreeBSD.org) must be added and *verified* as an email on your GitHub account (Settings > Emails).
• UID on Primary Key: The address must be a User ID (UID) on your *primary* PGP key. It's important to note that emails are associated with UIDs of the primary key, not directly with subkeys. While subkeys perform the signing, the attribution and verification against email addresses happen through the primary key's UID list. GitHub checks if its copy of your primary key has a UID that matches the committer's email.

Understanding these details is vital for maintaining robust security practices and ensuring that your software project metrics accurately reflect verified contributions. If, after following these steps, your commits still show "Unverified," then it might indeed be a more complex bug, warranting further escalation with specific key IDs and commit SHAs.

This community insight underscores the importance of proper GPG key management on GitHub, transforming confusing "Unverified" github alerts into clear, verified contributions.