Setup for Another Gitlab Instance ​

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

Tell Forge about the Instance ​

While Forge knows about https://gitlab.com (and a few other well-known instances, see its value) it has to be taught about other Gitlab instances. Forge instances are configured using the option forge-alist (also see its docstring). The entry for https://gitlab.com in that variable looks like this:

emacs-lisp
("gitlab.com"                       ; GITHOST
 "gitlab.com/api/v4"                ; APIHOST
 "gitlab.com"                       ; WEBHOST and INSTANCE-ID
 forge-gitlab-repository)           ; CLASS

For historic reasons, APIHOST actually has to be a host followed by a path.

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

emacs-lisp
(push '("example.com"               ; GITHOST
        "example.com/api/v4"        ; APIHOST
        "example.com"               ; WEBHOST and INSTANCE-ID
        forge-gitlab-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 colleague.

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

Set your Username ​

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

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

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

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

Create and Store an Access Token ​

Visit your forge in a browser. Follow a link to "Preferences" and from there to "Access Tokens". On that page generate a new "Personal access token" using the api, read_api and read_user 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:

emacs-lisp
(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:

emacs-lisp
(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 either the same as the second element of the entry we added to forge-alist, or that element with the path suffix removed. For example, if the APIHOST, specified in an forge-alist entry, is example.com/api/v4, then you can use example.com/api/v4 or example.com.

    Historically only the former was supported, but that was a design mistake, which we are now stuck with, and using just example.com as APIHOST in ~/.authsource is now recommended. For the time being, in forge-alist you must still always use example.com/api/v4 as APIHOST.

    If you instead use the auth-source-pass backend, then you must use example.com as the value of host. Using example.com/api/v4 does not work with that backend.

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