Introducing the Gitlab Issues plugin for Obsidian

If you’ve not heard of Obsidian yet, it’s a Personal Knowledge Base system, which works on plain text files in Markdown format.

Crucially for me, it’s an application that is installed locally that works on your local files which are in plain text format.

This means there are no proprietary document formats to deal with, I’m not locked in to any online cloud provider, and at the end of the day if Obsidian ever disappears off the map, all my important data is still accessible in my local plain text files. These are critical factors for me if I’m to pour all my notes into any app.

Obsidian is available for all platforms - Windows, Mac, Linux, Android and iOS.

Gitlab is a service that provides source code services such as Git and Mercurial for hosting code and associated artefacts. It is available as a cloud service with a free tier at Gitlab.com but also can be installed as a private, on-premises solution for larger organisations.

My need for the Gitlab Issues plugin for Obsidian began when I started to manage all my tasks in Obsidian. Once I had it configured the way I wanted, I was really pleased, but there was one thing missing - I had a second source of tasks for all the software applications I work on, and all these tasks were in Gitlab.

So, being a capable programmer, I did what anyone else would do and put together my own solution, to import Gitlab issues, via the Gitlab API, into my Obsidian vault.

I’m pleased to announce that yesterday, the plugin was approved and is now available in the official Obsidian Community Plugins database. This means you can install it directly from within the Obsidian settings area.

How does the plugin work?

The premise of the plugin is pretty simple. It will query the Gitlab API for issues, and create Obsidian note files for each issue that is returned. If an issue is no longer returned by the API, the Obsidian note is removed.

This means that the notes themselves should certainly be considered read-only. Any edits you make will be lost. However, the master source of knowledge for these issues is on Gitlab and must stay on Gitlab, so this ephemeral nature of the notes is by design, not accident.

To get started, simply browse to the Community Plugins section of the Obsidian settings, and browse for “Obsidian Gitlab Issues”. Install the plugin.

You then need to create a Gitlab token with API privileges over at Gitlab. Do not share this with anyone.

Back in Obsidian, browse to the plugin settings screen which looks like this:

Enter the API token in to the Personal Access Token field, choose an Output Folder, and you’re ready to go.

If you enable the ribbon icon, then clicking this will immediately load in any issues you have waiting in your Gitlab. Otherwise, issues are loaded 30 seconds after you start Obsidian and then every 15 minutes.

The default is to load an issues that have due dates in the next month, but this is configurable using any of the filter settings that are provided by the Gitlab Issues API.

How to use the issue notes in your Obsidian vault?

So now you have a set of notes, each representing a Gitlab issue. You can use and present these any way that you like, and the options in Obsidian are vast.

I suggest the way to get started quickly is with the excellent DataView Plugin to create lists of upcoming issues to embed anywhere you like in your vault. For example:

dataview  
TABLE WITHOUT ID file.link AS "Task", dueDate AS "Due Date" from "@Data/Gitlab Issues"  
SORT dueDate  

If you then close an issue on Gitlab, or change its due date to be further in the future, the issue will be removed from your vault, and the DataView list will no longer show the issue.

Once you have this set up and working, you can mess around with things to your heart’s content.

The plugin is still quite new but has been pretty well tested. If you do run into problems or have any other questions please leave a comment here or create an issue on the Github repository where the source code is hosted.