2 Getting Started

Each package that uses Ghub uses its own token. Despite that, chances are good that after successfully configuring one package you can just start using another package pretty much instantly.

If the necessary token to access a Github instance is not available when a package makes an API request, then a setup wizard pops up, and after answering a few questions you are good to go. Even the request that caused the wizard to be summoned should succeed and for most users this should be true even when configuring the very first token.

However, in some situations some manual configuration is necessary before using the wizard, or the wizard cannot be used at all:

• If you don’t want to use the wizard then you don’t have to and can create tokens manually as described in Manually Creating and Storing a Token.
• Unfortunately only Github supports the creation of tokens by using the API. If you want to access another forge, then you have to create the token manually as describe in Manually Creating and Storing a Token. Also see Support for Other Forges.
• If you want to access a Github Enterprise instance, then you have to tell Ghub about that before the wizard makes its appearance by setting the Git variable github.host. You also have to tell Ghub your username for that instance using the variable github.HOST.user even if it is the same as on Github.com.

  These variables are documented in Configuration Variables. Also see Setting the Username. TL;DR: If your Github Enterprise instance is hosted at git.example.com and your username on that instance is jtribbiani, then set github.host to git.example.com/api/v3 in every repository cloned from that instance (i.e. do not set it globally) and globally set github.git.example.com/api/v3.user to jtribbiani. The latter is necessary even if your username on Github.com is the same.

  For some Github Enterprice instances /api has to be used instead of /api/v3 as shown above. If the wizard fails in both cases, then try creating the token manually.

• If the variable github.user (or github.HOST.user for an Enterprise instance) is unset when the wizard is first summoned, then you are asked to provide your username. That value is then stored globally to avoid having to ask you that question once per repository. If you have multiple accounts on Github.com (or a Github Enterprise instance), then you have to explicitly tell Ghub about that. This can be done by setting the repository-local values of the appropriate variable before the wizard is invoked.
• You might forget to do the above, which is why it is important to carefully read the output of the wizard. If it turns out that you forgot to set a variable, then you must abort, set the variable, and repeat the request to trigger the wizard again.
• The setup wizard should work even if you have enabled two-factor authentication. However if your Github Enterprise instance enforces Single Sign-On as an additional security measure, then you are out of luck and have to create the token manually as described in Manually Creating and Storing a Token.

The variables mentioned above — and others — are documented in Configuration Variables and the setup wizard is documented in Interactively Creating and Storing a Token.