Documentation gap regarding email address verification

[jpw]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

This is the closest relevant article I could find:
https://github.com/github/docs/blob/main/content/authentication/troubleshooting-commit-signature-verification/index.md

What part(s) of the article would you like to see updated?

This may require updates to a few related pages, as it relates to what I feel are documentation gaps around the issue I hit, which I will describe below.

I don't have good enough knowledge of GH or the docs to be able to suggest specific edits, sorry.

Additional information

I was trying to ensure my commits were signed and verified. I am pretty sure I had this set up years ago, when GH anonymous email addresses were of the form username@users.noreply.github.com not ID+username@users.noreply.github.com

I created a new GPG key, uploaded that to GH, all seems fine. Signing commits locally was working:

$ git log --show-signature -1
...
gpg: Signature made Thu 27 Feb 15:23:04 2025 GMT
gpg:                using EDDSA key REDACTED
gpg: Good signature from "jpw <683955+jpw@users.noreply.github.com>" [ultimate]
Author: jpw <683955+jpw@users.noreply.github.com>
Date:   Thu Feb 27 15:23:04 2025 +0000

But when looking at the verification status in my list of commits on GH, when I clicked on the "Unverified" badge thingy, the UI popup said: "The email is this signature does not match the committer email".

Looking at my local git config I had:

user.email=683955+jpw@users.noreply.github.com
user.name=jpw

So I looked again my the associated GPG key on my machine, and in the GH UI:

Email addresses look the same, in my mind, contrary to the previous "does not match" message. As it was not clear to me at this stage what addresses were being referred to.

However the GPG key bit of the settings page (as per the image) hints that the email address was Unverified. And they have to be verified for signing I think, so I am now guessing that is the problem.

So I click "Unverifed" on that button in the screengrab. That leads to the email address settings page. All the docs I saw say that to verify the email address there should be a "verify" link, but this appears not to exist for @users.noreply.github.com addresses. All my (private) addresses are verified.

Now I was stuck. Some web searching revealed the problem:
https://superuser.com/questions/1512137/which-email-to-sign-commits-with-for-github-and-retain-privacy

The old style no-reply GitHub email address was what was what shown in the GitHub interface (i.e. username@users.noreply.github.com).
I had to force the account to use the new style. To do this, in Github, go to settings ... Emails. Then un-select the checkbox for Keep my email addresses private, then re-select it again. This should result in the email address shown in the text below the text box being updated to the format ID+username@users.noreply.github.com

I am guessing that because I had this set up ages ago, before the anon email format changes, on the email page I still had:

Because you have email privacy enabled, PRIVATE_ADDRESS will be used for account-related notifications as well as password resets. jpw@users.noreply.github.com will be used for web-based Git operations, e.g., edits and merges.

So turning privacy on and off again updated that value in the page to the ID+username@users.noreply.github.com format, so now the email addresses "matched" and victory was mine and my commits were Verified. The fix was rather unintuitive though, IMO.

It's entirely possible I missed some documentation somewhere! But there's a few possible issues here:

1. "The email is this signature does not match the committer email" message is maybe vague? It matches the committer email according to the local git config settings, and also that in the GPG key, and my anon email address in GH - but not the address used for this functionality. The docs I saw hint at the more common problems of these other email addresses not matching i.e. it's a key vs GH config issue or similar key problem.
2. The UI associated with the associated GPG key in the screengrab claims the address was "Unverified" which... is kind of a red herring?
3. I could not see any docs hinting what to do if a @users.noreply.github.com address is "Unverified"
4. If, on the email settings page, the message "Because you have email privacy enabled, PRIVATE_ADDRESS will be used for account-related notifications as well as password resets. jpw@users.noreply.github.com will be used for web-based Git operations, e.g., edits and merges." said something about signing commits, this might have been a useful clue for me.
5. Plus addressing being technically a different email address to the non-plussed version is a bit of a subtle difference, in the same way a URL and URI are different. I can see why you need to be strict in this instance though. But again, I can imagine users thinking they are "not different addresses" when technically they are different addresses pointing to the same email account might be confusing. Again, maybe some disambiguation... somewhere... might help.
6. Maybe there should be a more explicit way of converting the problematic address to the new format rather than "turning privacy off and on again"?

I expect this issue will affect users with older accounts migrating to the newer key? address? formats. Not sure why my setup stopped working. Possibly because they were old keys, or in a no longer supported format.

Sorry for the rather long and rambling issue! But as you can see it was a tricky one to fix, and could potentially touch several areas of the GH UI and pages in the docs. Thanks for having a look.

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[subatoi]

@jpw Thanks for raising an issue and providing such detail, and I'm sorry you had that experience

Just to set expectations appropriately, we're only able to fix confirmed issues with the content on docs.github.com, and it seems like there are a few things going on here—primarily with the UI—that I can feed back to relevant teams about internally on your behalf. I'm afraid, since we're not GitHub Support, I can't guarantee a timeframe for a response, though. If we do identify some kind of specific issue, we can look at adding or fixing docs if necessary, but I think it's more likely this is an edge case (that's not to say for definite that it's not a bug).

It would help if you could either raise a ticket with GitHub Support themselves if your plan includes it, or if not, you could consider opening a community discussion to see if other users have experienced this to confirm or deny my suspicion about the edge case factor (I know you linked to a Stack Overflow post).

[github-actions]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀

[jpw]

Hi @subatoi thanks very much for your message, and I agree with your assessment of the matter.

As suggested, I have raised an issue with GH Support.

[Jessie822-dev]

👍

[subatoi]

Many thanks @jpw — as you've opened a Support ticket we've closed this one out (we're confident it's not an issue with the documentation). Please feel free to add a new comment if it transpires there is a documentation issue, and we can reopen this. Thank you for your help!