2.2 Setup for Another Github Instance

Before you setup a Github instance that is not https://github.com, please set that up first. The setup for https://github.com is easier and if that works, but the setup for the other Github instance fails, then we can tentatively narrow the issue down to the parts that differ between https://github.com and other instances.

Tell Forge about the Instance

While Forge knows about https://github.com, it does not know about your other Github instances. Forge instances are configured using the option forge-alist (also see its docstring). The entry for https://github.com in that variable looks like this:

("github.com"                       ; GITHOST
 "api.github.com"                   ; APIHOST
 "github.com"                       ; WEBHOST and INSTANCE-ID
  forge-github-repository)          ; CLASS

You have to add an entry for your instance. For example, assuming you company uses https://example.com, this might be correct:

(push '("example.com"               ; GITHOST
        "api.example.com"           ; APIHOST
        "example.com"               ; WEBHOST and INSTANCE-ID
        forge-github-repository)    ; CLASS
      forge-alist)

Your company may use hostnames that follow a different format. You should be able to easily determine and verify GITHOST and WEBHOST, but determining APIHOST is more difficult; you might have to ask a coworker. APIHOST could be something like api.example.com, but it could also be something like example.com/api.

If the REST API’s end point is /v3 and the GraphQL API’s end point is /graphql, then use something like example.com/v3 as APIHOST. This is a historic accident. See https://github.com/magit/forge/issues/174.

We will use INSTANCE-ID (aka WEBHOST) and APIHOST below.

Set your Username

Inform Forge about your username for the Github instance in question:

git config --global github.INSTANCE-ID.user USERNAME

So if INSTANCE-ID is example.com and USERNAME is tarsius then use:

git config --global github.example.com.user tarsius

Create and Store an Access Token

Visit your forge in a browser. Follow a link to "Settings", from there to "Developer settings", from there to "Personal access tokens", and finally to "Tokens (classic)". On that page generate a new token using the repo, user and read:org scopes. Do not close the browser window just yet, because the token will only be shown once.

The built-in Auth-Source ((auth)Top) package is used to store the token generated in the previous step. The auth-sources variable controls how and where Auth-Source keeps its secrets. The default value is a list of three files: ("~/.authinfo" "~/.authinfo.gpg" "~/.netrc"), but that can lead to confusing behavior, so you should make sure that only one of these files exists, and then you should also adjust the value of the variable to only ever use that file, for example:

(setq auth-sources '("~/.authinfo"))

In ~/.authinfo secrets are stored in plain text. If you don’t want that, then you should use the encrypted ~/.authinfo.gpg instead:

(setq auth-sources '("~/.authinfo.gpg"))

Make sure you put one of these forms in your init file and to evaluate it in the current Emacs instance as well, by placing the cursor after the final closing parenthesis and typing C-x C-e (eval-last-sexp).

Next add a line like the following to the chosen file:

machine APIHOST login USERNAME^forge password TOKEN

• APIHOST must be the same as the second element of the entry we added to forge-alist. In the above example that would be api.example.com. Do not instead use GITHOST or INSTANCE-ID (aka WEBHOST).
• USERNAME must be the same username you used above as the value of the Git variable. You must append ^forge to that, without any space in between.
• TOKEN is the token you generated earlier.

Finish by typing M-x auth-source-forget-all-cached RET. If you don’t do this, then Auth-Source may fail to look up the token.