Basic Concepts, Arguments and Variables ​

(If you are trying to configure Forge for https://github.com and/or https://gitlab.com, then you can skip this section.)

Originally Ghub supported only Github but now it also supports Gitlab, Gitea, Gogs and Bitbucket. Because of that, the function ghub-request defaults to acting on a github forge, but can be told to act on other forges using the FORGE argument.

The FORGE argument only specifies what kind of forge we are accessing, not which host specifically. The HOST argument can be used to select the instance. For some forges a default instance is defined:

  • Forge github defaults to host api.github.com.
  • Forge gitlab defaults to host gitlab.com/api/v4.
  • Forge bitbucket defaults to host api.bitbucket.org/2.0.
  • No canonical host exists for the gitea and gogs forges and localhost:3000/api/v1 is used as the default host in both cases.

Together the FORGE and HOST arguments specify the forge type and instance. In addition to that, it is also necessary to specify on whose behalf the request is being made, which can be done using the USERNAME and AUTH arguments. For example:

emacs-lisp
(ghub-request "GET" "/user" nil
              :forge 'github
              :host "api.github.com"
              :username "tarsius"
              :auth 'forge)

Having to specify these arguments for every request is inconvenient. Additional variables and convenience functions can be used to make that unnecessary in most cases.

(But for debugging purposes the above explicit form is very useful. You will obviously have to change the value of USERNAME and you should use ghub as AUTH when first trying this at home.)

These variables can be set globally and/or for a specific repository.

  • For "api.github.com" (aka the API of https://github.com) the Git variable github.user specifies the user.
  • For another github instance the Git variable github.HOST.user specifies the user. The HOST in that variable name is the same as the value of the HOST argument of the called function.
  • Instead of specifying the HOST in every function call, the Git variable github.host can be used. This should only be set locally.

These github specific variables are discussed in more detail in Github Configuration Variables.

For gitlab and bitbucket forges similar variables are available:

  • gitlab.user specifies the https://gitlab.com user.
  • gitlab.HOST.user specifies the user for the HOST gitlab instance.
  • gitlab.host specifies the gitlab host, unless the HOST argument is non-nil
  • bitbucket.user specifies the https://bitbucket.org user.
  • bitbucket.HOST.user specifies the user for the HOST bitbucket instance.
  • bitbucket.host specifies the bitbucket host, unless the HOST argument is non-nil.

For the gitea and gogs forges some similar variables are available, however for some of the ghub.* variables no equivalent variable exist for these two forges:

  • gitea.user is not used because no canonical gitea instance exists.
  • gitea.HOST.user specifies the user for the HOST gitea instance.
  • gitea.host specifies the gitea host, unless the HOST argument is non-nil
  • gogs.user is not used because no canonical gogs instance exists.
  • gogs.HOST.user specifies the user for the HOST gogs instance.
  • gogs.host specifies the gogs host, unless the HOST argument is non-nil