2.2 Interactively Creating and Storing a Token

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:

• Host usually 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.
• User should 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.
• Package should 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 package.

  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 the variable ghub-github-token-scopes before triggering the wizard again.

• Each PACKAGE has 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.

• The value of auth-sources is 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.

• When creating a token, it is necessary to provide a token description. Ghub uses descriptions that have the form "Emacs package PACKAGE @ LOCAL-MACHINE".

  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 returned by 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 token.

  The former is recommended and also easier to do, using the variable ghub-override-system-name. See Configuration Variables for details.

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).