4 Using Ghub in a Package

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 ghub-request on behalf of which package a request is being made by passing the symbol PACKAGE as the value of its AUTH argument.

(ghub-request "GET" "/user" nil :auth 'PACKAGE)

Variable: PACKAGE-github-token-scopes

This variable defines the token scopes requested by the package named PACKAGE. The doc-string should explain what the various scopes are needed for to prevent users from giving PACKAGE fewer permissions than it absolutely needs and also to give them greater confidence that PACKAGE is only requesting the permissions that it actually needs.

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.

Command: ghub-token-scopes

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 HOST, USERNAME and PACKAGE when 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...)