Ghub uses a different token for every package as well as for every machine from which you access the Github API (and obviously also for every Github instance and user). This allows packages to only request the scopes that they actually need and also gives users the opportunity to refuse access to certain scopes if they expect to not use the features that need them.
Usually you don’t have to worry about creating and storing a token yourself and can just make a request. Note however that you don’t have to use the setup wizard described below. Alternatively you can perform the setup manually as described in the next section.
If you make a request and the required token is not available yet, then the setup wizard will first ask you something like this:
Such a Github API token is not available: Host: api.github.com User: USERNAME Package: PACKAGE Scopes requested in `PACKAGE-github-token-scopes': repo Store on Github as: "Emacs package PACKAGE @ LOCAL-MACHINE" Store locally according to option `auth-sources': ("~/.authinfo" "~/.authinfo.gpg" "~/.netrc") If in doubt, then abort and first view the section of the Ghub documentation called "Interactively Creating and Storing a Token". Create and store such a token? (yes or no)
If you don’t have any doubts, then answer "yes". Lets address some of the doubts that you might have:
Hostusually is "api.github.com" and that is usually what you want. If you are trying to access a Github Enterprise instance, then it should be something else and you have to set the value manually before the setup wizard is summoned, as described in the parent section.
Usershould be your Github.com (or Github Enterprise instance) username. If it is something else and it doesn’t look like a simple typo, then you should read the parent section again. In either case you have to abort.
Packageshould be the name of the package you are using to access the Github API.
If it is
ghub, then the package author disregarded that convention
and you should probably report a bug in the issue tracker of that
Or you yourself are using
ghub-request or one of its wrappers
directly, in which case this is expected and perfectly fine. In
that case you might however want to abort and change the value of
ghub-github-token-scopes before triggering the wizard
PACKAGEhas to specify the tokens that it needs using a variable named
PACKAGE-github-token-scopes. The doc-string of that variable should document why the various scopes are needed.
The meaning of the various scopes are documented at https://magit.vc/goto/f63aeb0a.
auth-sourcesis shown. The default value causes secrets to be stored in plain text. Because this might be unexpected, Ghub additionally displays a warning when appropriate.
WARNING: The token will be stored unencrypted in "~/.authinfo". If you don't want that, you have to abort and customize the `auth-sources' option.
Whether that is something that needs fixing, is up to you. If your answer is yes, then you should abort and see How Ghub uses Auth-Source for instructions on how to save the token more securely.
Github uses the token description to identify the token, not merely as something useful to humans. Token descriptions therefore have to be unique and in rare cases you get an additional prompt, asking you something like:
A token named "Emacs package PACKAGE @ LOCAL-MACHINE" already exists on Github. Replace it?
You might see this message when you have lost the old token and want to replace it with a new one, in which case you should obviously just proceed.
Or two of your computers have the same hostname, which is bad practice because it gains you nothing but leads to issues such as this. Or you are dual-booting on this machine and use the same hostname in all operating systems, which is a somewhat reasonable thing to do, but never-the-less leads to issues like this.
In either case you will have to use something other than the value
system-name to identify the current machine or operating
system. Or you can continue to identify different things using the
same identifier, in which case you have to manually distribute the
The former is recommended and also easier to do, using the variable
ghub-override-system-name. See Configuration Variables for
After the above prompt you are also asked for your username and
password. If you have enabled two-factor authentication, then you
also have to provide the authentication code at least twice. If you
make sure the code is still good for a while when asked for it first,
then you can just press
RET at the later prompt(s).