How to Use GitLab as a Project Management Tool

A workflow to improve your productivity and properly manage projects without having to use complex solutions for agile project management.

6 min readMay 25, 2020

Disclaimer: This article is primarily intended for those who are not already familiar with GitLab Milestones or conventional commits and who want to effectively manage their project without having to use other complex solutions.

Why GitLab?

GitLab is not only about hosting your code. It also enables agile project management whether from very simple issue tracking to Kanban and Scrum styles of agile delivery. On GitLab you can manage issues, visualize the status of work across your sprints and track the effort and resolution priority as effectively as with dedicated project management applications.

Another reason for using GitLab is that it’s more suitable for developers than the other applications that are too complex to be used effectively. So what if you could take advantage of GitLab functionalities to actually use it as a better approach to manage your projects?

Let’s see how I manage to do it within my project teams.

GitLab Milestones

According to the GitLab documentation:

Milestones in GitLab are a way to track issues and merge requests created to achieve a broader goal in a certain period of time. Milestones allow you to organize issues and merge requests into a cohesive group, with an optional start date and an optional due date.

So basically, milestones are just time-boxed boards used to manage sprints, visualizing the work as it flows through the project, with a strong focus on delivery and velocity.

In my projects, I like to create 3 kinds of milestones: the sprint, quarter, and shape-up milestones.

Sprint milestone

The sprint milestone is the one that we are currently working on. It contains all the issues of the current sprint and it is named using the version of the software that we are developing. If the sprint is about developing the version 1.2.0 of the project, the milestone will just be named 1.2.0. By the way, this is also how the GitLab team usually names their milestones.

Quarter backlog milestone

For each quarter, my team and I will potentially deliver multiple versions of our software. And each version milestone is actually filled by pulling issues from the corresponding quarter milestone and assigning them to that specific sprint milestone. This allows for a fairly small backlog since it only contains the issues that could potentially be assigned and achieved during the current quarter.

Shape-Up milestone

We also like to create a milestone called “Shape up”. In this milestone, we integrate all the issues that are not well defined, still vague ideas, and for which the whole team still has to think about. We actually have a weekly meeting during which we think about whether a particular issue should finally integrate a sprint or not. To fully understand this “shape up” process I strongly recommend that you take a look at this very interesting e-book from Basecamp.

Issues

Now let’s talk about issues.

Issues are the fundamental medium for collaborating on ideas and planning work in GitLab. Issues can allow you, your team, and your collaborators to share and discuss proposals before, and during, their implementation.

It’s important to add some labels to the issues to quickly identify which component of your application is involved, and what type of issue it is (a bug, a feature request, etc.). The GitLab issue boards have great filtering capabilities, so the more your issues are well labeled, the easier it will be to prioritize and align your team to the business needs. You’ll find below some of the labels that I like to use.

Also, as soon as someone is assigned to an issue, the issue automatically switches to the “Ongoing” column of the milestone, making it easy to know where the work is from a team perspective.

Labels examples

You’ll find below some labels that I like to use to create views and representations of the backlog that help to plan and prioritize the work.

Type labels

Type: Bug
Type: Feature
Type: Feature Request
Type: Refactor
Type: Documentation
Type: Chore
Type: Discussion
Type: Research
Type: UX/UI

Component labels

Component: Front
Component: API
Component: Engine etc.

Scope labels

Scope: Admin page
Scope: Search
Scope: User profile etc.

Status labels

Status: On Hold
Status: Shape-up etc.

Topic labels

Topic: Data collection
Topic: Monitoring
Topic: Data quality
Topic: Security etc.

Merge requests

The main benefit of using GitLab is that it maintains strong traceability to execution by linking your issues to the actual state of the development through the merge requests where developers implement and deliver the code changes.

I also strongly recommend using conventions for the titles of your merge requests. Especially if you use the GitHub Flow and squash your commits, the title of your merge request will then corresponds to the commit title on the master branch. I use the very common git commits conventions described below.

Commits conventions

The convention that I use suggests to apply this commit message format:

<type>(<scope>): <subject>

Where type can be:

feat (new feature for the user)
fix (bug fix for the user)
docs (changes to the documentation)
style (formatting, missing semicolons, etc.)
refactor (refactoring production code, eg. renaming a variable)
test (adding missing tests, refactoring tests)
chore (updating webpack config etc)

scope could be:

api
front
internal etc.

And the subject must uses the imperative, present tense.

feat(api): add users profile endpoint

Example of a valid merge request title

Merge request description

The description of the merge request is also very important. This is actually where all the project management magic happens.

Indeed, as said above, you can link your merge request to the issue you’re currently assigned to. If the merge request is related to the issue but the issue will not yet be resolved after the merge request being merged, add

Related to # <ID_of_the_issue> or Mentions # <ID_of_the_issue>

to your MR description. This will make it easy to find the merge request from the issue context and vice versa. On the other hand, if the changes applied by the merge request solve the issue, add Closes # <ID_of_the_issue> within the MR description. This way, once the MR is merged into the master branch, the issue will be closed automatically and switched to the "Completed issues" column of the milestone.

Using these helpers, you’ll no longer need to manually update the issues board, GitLab does it automatically for you. And that’s exactly what most developers want, not having to manually update the board.

You can also mention or close a cross-project issue by mentioning the full link to that issue.

Awesome commit messageFix #20, Fixes #21 and Closes group/otherproject#22.
This commit is also related to #17 and fixes #18, #19
and https://gitlab.example.com/group/otherproject/issues/23.

And that's it! As you can see there is way less process than using an agile project management application and it's also easier for developers (as well as project managers) to manage the project.

Slack integration

One more thing that I love about GitLab is that you can easily add a Slack notifications service to your project. Using webhooks, you and your team can be notified on Slack whenever a new issue or merge request is opened or closed which is very handy and will make you way more reactive and effective.

There are a lot of other great features that GitLab supports such as the Group Issue Board, the Description Templates, Time Tracking, etc. making it a major competitor against project management applications. Feel free to check out this Jira vs. GitLab comparison if you want more information about it.

Thank you for reading me and stay tuned, more articles are coming soon ✌️

Follow me on twitter @hasniarif, I post things about productivity, growth mindset, Tech, React.js, GraphQL, and more!