Every package should use its own token. This allows you as the author of some package to only request access to API scopes that are actually needed, which in turn might make it easier for users to trust your package not to do unwanted things.
The scopes used by
PACKAGE have to be defined using the variable
PACKAGE-github-token-scopes, and you have to tell
behalf of which package a request is being made by passing the symbol
PACKAGE as the value of its
(ghub-request "GET" "/user" nil :auth 'PACKAGE)
This variable defines the token scopes requested by the package
PACKAGE. The doc-string should explain what the various
scopes are needed for to prevent users from giving
permissions than it absolutely needs and also to give them greater
PACKAGE is only requesting the permissions that it
The value of this variable does not necessarily correspond to the scopes that the respective token actually gives access to. There is nothing that prevents users from changing the value after creating the token or from editing the token’s scopes later on.
So it is pointless to check the value of this variable before making a request. You also should not query the API to reliably determine the supported tokens before making a query. Doing the latter would mean that every request becomes two requests and that the first request would have to be done using the user’s password instead of a token.
Because we cannot be certain that the user hasn’t messed up the scopes, Ghub provides this command to make it easy to debug such issues without having to rely on users being thoughtful enough to correctly determine the used scopes manually.
Just tell users to run
M-x ghub-token-scopes and to provide the
correct values for the
prompted, and to then post the output.
It is to be expected that users will occasionally mess that up so this command outputs not only the scopes but also the user input so that you can have greater confidence in the validity of the user’s answer.
Scopes for USERNAME^PACKAGE@HOST: (SCOPE...)