Gitlab Issues is a free tool built into Gitlab Cloud and Community Editions that makes it easier to track software development progress. It supports many of the same features as competitors like Jira, while being easier to use.

Getting Started

If you've used Jira, Trello, or other Kanban-based organization software, you'll find Gitlab Issues to be quite familiar. However, it has a lot of features that set it apart from Jira.

Like Jira, you can create individual issues, assign them to people, and link them to other issues (though, linking issues isn't available in Gitlab's FOSS version). The concept of "Epics" is here, named "Milestones." Issues can be assigned to a milestone, and used to track progress of major features. "Epics" are actually available in Gitlab's Ultimate edition, but they share many of the same features as Milestones, which are free for everyone.

The primary organizational tool used by Gitlab issue are Kanban boards, very similar to Jira and Trello's implementation. You can create multiple boards, and switch between them quickly using the dropdown on the main page. Within these board, you can create individual cards.

Gitlab's boards function a bit differently from Jira's. In Jira, and issue can be assigned to an Epic, linked to other issues, have child issues created underneath it, and be placed in a specific list.

In Gitlab Issues, issues can have multiple "labels" at once. Each list in the Kanban board is actually just a collection of all cards that have that label.

Of course, labels don't need to have a list associated with them, and can simply function as additional tags you can apply to issues. For an example of what this looks like in practice, you can check out Gitlab's personal issues board, which is quite full:

While it can look like a mess, this has its upsides. Issues can be searched for quite easily, allowing members to focus on particular areas of development using the same lists and systems you have in place for the board as a whole. Searching by label, milestone, and weight are supported.

Plus, if you really can't stand all the color, there's an option to toggle it off from the main board page.

To add a new list, you'll need to create a label. Click "Add List," and select "Create Project Label."

This will bring up a dialog where you're free to name the label and give it a color code.

This will add a new list to your board. If you just want to add labels, or edit the description of labels, you can do so from the "Labels" tab in the sidebar.

If you decide that you would like to add a list for the label after all, you can do so. A new list will be created, and all existing issues with that label will also show up in the new list.

This applies to every issue with multiple labels---if there are lists for two or more labels the issue belongs to, the issue will be "duplicated" into both lists. Once you move the issue to "Done," all the duplicates will disappear.

If you click on an issue, you'll be brought to that issue's page. Here, you can comment and discuss the issue much like you would on Github. You can create a merge request from here as well.

In the sidebar, you'll find settings for changing the issue's metadata, such as the labels, milestones, due dates, and assignees.

Importing Issues from Jira

If you're already using Jira, and want to make the switch to Gitlab Issues, you can export all of your issues from Jira and import them into Gitlab.

From Jira's main menu, click "Issues And Filters" and find "All Issues." This will display a list of every issue, which you can filter further if you'd like. Click the "Export" button in the top right-hand corner, and choose "Export Excel CSV (all fields)"

This will download a CSV file containing all of your issues and their related info.

You can import this into Gitlab under the "Issues" tab, by pressing the "Import CSV" button in the top right menubar.

Gitlab will import all your issues, which may take a while, depending on how many you have. It will send you an email once it's done though.

The switch won't be entirely seamless, as you'll probably have to do a lot of reorganizing, but you won't be starting from scratch.