lab.el

lab.el is an Emacs package that provides a simple integration with GitLab (managed or self-hosted).

Basics

lab.el is designed to make your daily interactions with GitLab easier. Want to quickly list latest merge requests for a project? You got covered! Want to create a merge request for the project you are currently working on, totally inside Emacs? You got covered! Want every function on GitLab API exposed as an elisp function? You are on your own. See Functionality summary down below for a quick rundown of what lab.el is capable of.

Workflow is generally completing-read based. You list and select an item (a project/merge request/pipeline/job) and then you trigger one of the listed actions that can be acted upon selected item. There are also other special interactive functions, like lab-create-merge-request. Also some functions work directly on current project you are working on (provided by project.el).

lab.el also supports embark, you can use (embark-act) on any kind of item and you’ll see all possible actions. This is generally useful for doing bulk actions (possibly using embark-act-all) as the primary feature of embark, listing actions of a target, is already covered by lab.el.

I extracted this package from my init.el as the feature set grew to a point that is too much to keep it in there. This may explain why some of the functionality that you expect a GitLab client would have is missing. It’s because I probably don’t use that feature.

Installation

Just download lab.el file and put it into your load-path, afterwards you can simply do the following in your init.el:

(require 'lab)

You can also use use-package

;; with straight:
(use-package lab
  :ensure t
  :straight (:host github :repo "isamert/lab.el"))

;; with quelpa:
(use-package lab
  :ensure t
  :quelpa (lab :fetcher github :repo "isamert/lab.el"))

Usage

Set the following variables and you are good to go:

;; Required.
(setq lab-host "https://gitlab.mycompany.com")

;; Required.
;; See the following link to learn how you can gather one for yourself:
;; https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token
(setq lab-token "YOUR-PRIVATE-GITLAB-API-TOKEN")

;; Optional, but useful. See the variable documentation.
(setq lab-group "YOUR-GROUP-ID")

See M-x customize-group lab for all customization options.

Functionality summary

Here is a quick rundown of features lab.el provides:

Projects

• List projects belonging to you or a group.
• Act on projects:
  • Open them in browser.
  • Clone single project or do a bulk cloning.
  • List merge requests of given project.
  • Show detailed information about given project.

Merge Requests

• List merge requests belonging to a group, a branch, a project or all merge requests that you created or assigned to.
• Act on merge requests:
  • Open them in browser.
  • Mark them as ready or as draft.
  • Rebase remote branch against the target.
  • List pipelines and act on them.
  • Show detailed information about given merge request.
• Create merge requests with an easy to use merge request wizard. It also let’s you edit details of your merge requests in markdown buffer with yaml header and shows you the diff generated by your merge request (using magit, if available).

Pipelines

• List pipelines belonging to a project or a merge request.
• Act on pipelines:
  • Open them in browser.
  • Trigger retries, cancellation or deletion.
  • Start watching given pipeline in background and get notified if pipeline finishes or requires a manual action.
  • List individual jobs of a pipeline and act on them.
  • Show detailed information about given pipeline.
• Automatically start watching pipelines after a push and get notified about their status. (See Extras/tips section below)

Jobs

• List jobs belonging to a pipeline.
• Show logs of a (latest) failing job in a nicely formatted Emacs buffer.
• Act on jobs:
  • Open them in browser.
  • Trigger retries, cancellation or deletion.
  • Show logs of a job on a nicely formatted buffer.
  • Show detailed information about given job.

Here are few screenshots to get a feel of what you would see while using lab.el:

By default, actions can be selected using read-multiple-choice. You can change this to a completing-read based action handler by modifying the lab-action-handler variable.

Other functions work in similar fashion, where you list something (projects/pipelines/jobs etc.) and act upon them. Here is how you create a merge request:

Extras/tips

Supplemental packages

Some packages enhances lab.el with extra features:

alertDesktop notifications for lab-watch-* commands. markdown-modeFor better lab-create-merge-request. magitShows you the diff generated by your merge request while creating a merge request with lab-create-merge-request. git-linkOpen current repository in browser easily. lab.el does not use this package but it’s nice to have if your workflow requires some manual interventions to GitLab UI.

Start watching your pipeline automatically

• After creating an MR:

  (add-hook lab-after-merge-requests-create-functions #'lab-watch-merge-request-last-pipeline)
      

• After pushing a commit:

  (add-hook YOUR-PUSH-HOOK #'lab-watch-pipeline-for-last-commit)
      

• If you are using magit, following advice may be used for triggering pipeline watcher after each push:

(define-advice magit-push-current-to-pushremote (:after (&rest _) start-watching-pipeline)
  (lab-watch-pipeline-for-last-commit))

project.el integration

You can integrate the lab.el functions you frequently use into project.el, like following:

(define-key project-prefix-map "M" #'lab-list-project-merge-requests)
(add-to-list 'project-switch-commands `(lab-list-project-merge-requests "List merge requests"))

(define-key project-prefix-map "P" #'lab-list-project-pipelines)
(add-to-list 'project-switch-commands `(lab-list-project-pipelines "List pipelines"))

Now List pipelines and List merge requests actions will be added to project.el actions list and you’ll be able to access them using C-x p M and C-x p P respectively.

Using as a GitLab API client

You can use the provided lab--request function write your on GitLab API wrappers:

;; Get *all* pipelines currently running on master.
(lab--request
 "projects/#{project}/pipelines"
 :scope "running"
 :ref "master"
 :%collect-all t)