Improve error message for GitHub API token permission failure

[jacktose]

Provide a detailed description of the proposed feature

When brew gist-logs (and maybe others?) fails because of insufficient scope on the GitHub API token, the only feedback is Error: Not Found, which does not point toward the solution.

Probably, the output should use this message, from utils/github/api.rb#L175-L180:

Your #{what} credentials do not have sufficient scope!
Scopes required: #{needed_scopes}
Scopes present:  #{credentials_scopes}
#{CREATE_GITHUB_PAT_MESSAGE}

I'm not sure where that message is used, or why it's not used in this case.

What is the motivation for the feature?

# Create GH token with no perms
export HOMEBREW_GITHUB_API_TOKEN=ghp_hunter2
$ brew gist-logs -p gettext
Error: Not Found

# Add gist perm to token
$ brew gist-logs -p gettext
https://gist.github.com/0b08a0f9fe9e3897125f9b5770091c6e

Error: Not Found is frustratingly unhelpful. It took me some trial and error to find the solution.

How will the feature be relevant to at least 90% of Homebrew users?

It will not. It will be relevant to users who use certain GitHub-related features of Homebrew.

What alternatives to the feature have been considered?

None, as far as I know. Though similar messaging is apparently present in utils/github/api.rb#L175-L180.

And similar issues were addressed in:
Linuxbrew/legacy-linuxbrew/issues/673
Homebrew/legacy-homebrew/issues/39864
Homebrew/legacy-homebrew/pull/50410

[Bo98]

We do have a general system already that works for just about anything else. For some reason the Gist API behaves differently like this. It's not normal for it to return 404 for things like that (unless accessing a private resource - which we're not), so it seems like a GitHub bug IMO. Particularly since x-accepted-oauth-scopes is also blank so it doesn't even suggest you have wrong scopes.

The best we could probably do is catch GitHub::API::HTTPNotFoundError around the GitHub.create_gist call in brew gist-logs and print a different message in that situation.

[MikeMcQuaid]

The best we could probably do is catch GitHub::API::HTTPNotFoundError around the GitHub.create_gist call in brew gist-logs and print a different message in that situation.

This makes sense to me 👍🏻