Software developer

Developer of webapps and more since 2016

25 Jun 2022

1.11k
Configure Magit Forges for self-hosted Gitlab

Tags

abstract

After some research and multiple tries and hours spent on it, I finally succeeded in configurating Magit Forges on macOS for a self hosted gitlab instance.

This article's reason is to describe the steps and gather resources for doing it.

For people who don't know what is Magit Forges :

  • Magit is the Emacs package for managing git repositories.
  • Forges is a Magit extention for extended features for topics management (issues, pull requests, merge requests, notifications)

Steps

create a token

The first thing to do is to create an api token for your code host service (gitlab, github, bitbucket..)

In gitlab, go to your profile, click on access token and generate an access token. See here for the permissions the token needs : https://magit.vc/manual/forge/Token-Creation.html.

Name it and save it somewhere

create a .authinfo file

In your home folder, create a file and name it .authinfo

insert this content :

machine {{GITLAB-HOST}}/api/v4 login {{YOUR-GITLAB-USERNAME}}^forge password {{YOUR-API-KEY}}

replace the content in the loud brackets by your gitlab host (ex gitlab.cds.intra in my case), gitlab username and the api key you just created.

encrypt the .authinfo into a .authinfo.gpg key

https://practical.li/spacemacs/source-control/forge-configuration.html?q=

From emacs, run the command M-x epa-encrypt-file. select the file .authinfo, When prompted "Select recipients for encryption", select "OK" , then enter a password for the key.

This will create the $HOME/.authinfo.gpg file

if using doom Emacs

add the forges package to magit by adding (magit +forges)

to the :tools section of your init.el to add forges

Then, in the config.el, add your self hosted gitlab url to the forge-alist variable :

(after! magit (push '("gitlab.cds.intra" "gitlab.cds.intra/api/v4" "gitlab.cds.intra" forge-gitlab-repository)
      forge-alist))

If your gitlab does not have a certificate, and you access it via http only, add this code to the config.el : https://github.com/magit/forge/wiki/Tips-and-Tricks#accessing-private-gitlab-instances-via-http

(after! magit (defclass forge-gitlab-http-repository (forge-gitlab-repository)
((issues-url-format         :initform "http://%h/%o/%n/issues")
(issue-url-format          :initform "http://%h/%o/%n/issues/%i")
(issue-post-url-format     :initform "http://%h/%o/%n/issues/%i#note_%I")
(pullreqs-url-format       :initform "http://%h/%o/%n/merge_requests")
(pullreq-url-format        :initform "http://%h/%o/%n/merge_requests/%i")
(pullreq-post-url-format   :initform "http://%h/%o/%n/merge_requests/%i#note_%I")
(commit-url-format         :initform "http://%h/%o/%n/commit/%r")
(branch-url-format         :initform "http://%h/%o/%n/commits/%r")
(remote-url-format         :initform "http://%h/%o/%n")
(create-issue-url-format   :initform "http://%h/%o/%n/issues/new")
(create-pullreq-url-format :initform "http://%h/%o/%n/merge_requests/new")
(pullreq-refspec :initform "+refs/merge-requests/*/head:refs/pullreqs/*"))))

(after! magit (add-to-list 'ghub-insecure-hosts "gitlab.cds.intra/api/v4"))

(replace gitlab.cds.intra by your gitlab url) This will enable insecure access to gitlab.

Import your first repository

You should be done.

From a magit repository, run the command M-x forge-add-repository

Enter your gitlab username when prompted for a user. This config is now located on your project's git repo or globally based on your choice. To see it, run git config --global --list if set globally or git config --list from a repository and git config --help to see how to delete/edit a key.

You should see the issues and merge requests imported in the minibuffer.

Tips to debug

When you get an error, run M-x debug-on-error then run again. You will get a stack trace you can analyse to find out what's going on.