2.3 Setup for Gitlab.com

Set your Username

First inform Forge about your https://gitlab.com username:

git config --global gitlab.user USERNAME

If you need to identify as another user in a particular repository, then you have to set that variable locally:

cd /path/to/repo
git config --local gitlab.user USERNAME

Create and Store an Access Token

Visit https://gitlab.com/-/profile/personal_access_tokens in a browser to generate a new 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:

(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 gitlab.com/api/v4 login USERNAME^forge password TOKEN

• The value of machine must be gitlab.com/api/v4. Variations of this won’t work.
• USERNAME must be the same as the value used for the gitlab.user Git variable above. 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.