7.1 Forge Functions and Variables

Originally Ghub supported only Github but now it also supports Gitlab, Gitea, Gogs and Bitbucket. The function ghub-request and all the ghub-METHOD convenience wrappers default to acting on a Github forge but can be told to act on another forge using their FORGE argument.

The FORGE argument only specifies what kind of forge to act on, not which instance. 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.

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.

These variables can be set globally and/or for a specific repository as explained in Configuration Variables with a focus on Github instances. To summarize:

• For 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.

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 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 gitea 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

ghub-request and ghub-METHOD can be used to make a request for any of the supported forge types, but except when making a request for a github instance, then that requires the use of the FORGE argument.

To avoid that, functions named FORGE-request and FORGE-METHOD are also available. The following forms are equivalent, for example:

(ghub-get ... :auth 'PACKAGE :forge 'gitlab)
(glab-get ... :auth 'PACKAGE)

These forms would remain equivalent even if you did not specify a value for the AUTH arguments — but you should not do that if you plan to share your code with others (see Using Ghub in a Package). If you do omit AUTH, then the request is made on behalf of the ghub package, regardless of the symbol prefix of the function you use to do so.

All FORGE-request and FORGE-METHOD functions, including but not limited to ghub-METHOD, are very simple wrappers around ghub-request. They take fewer arguments than ghub-request and instead pass constant values for the arguments METHOD and/or FORGE.