GitLab: templates for Merge Requests

Intro

GitLab is a well-established tool that hardly needs any introduction. This article is more like some notes to my future self.

In GitLab, there are convenient user groups and even subgroups.

In GitLab, you use groups to manage one or more related projects at the same time. 
You can use groups to communicate with all group members and manage permissions for your projects. If someone has access to the group, they get access to all the projects in the group.
You can also view all of the issues and merge requests for the projects in the group, and analytics about the group's activity.
Read more at GitLab.

Moreover GitLab offers handy templates for Merge Requests (MR), where these groups can be used.

Templates exist to standardise processes, save time and reduce mistakes in the MR's descriptions. Why create a new MR from scratch every time when you can make a good template once and reuse it?

GitLab templates eliminate repetitive writing and set a clear structure — everyone knows what information to provide and how it should look. This simplifies the creation process for the author and makes it easier for reviewers to understand what’s going on.

What to specify and where templates live

In templates you can specify:

• users or groups (if you just want to notify them);
• users or groups as reviewers;
• assign necessary labels;
• assign yourself as the assignee;
• set Draft status;
• set Ready status;
• and much more.

A detailed list of “GitLab Quick Actions” is available in the documentation.

How to add a template to a repository:

• path: .../-/tree/master/.gitlab/merge_request_templates
• file: *.md

For example:
.../-/tree/master/.gitlab/merge_request_templates/Backend-ALL.md

Real example

In earlier versions of our templates, we specified exact usernames. When new employees were hired or team members switched teams, we had to manually update all templates where those names appeared. This was inconvenient not only because we needed to edit every template, but also because it was easy to forget — especially when templates were existing across multiple repositories.

Now we add users to specific groups and from there the magic takes care of itself – no human intervention needed.

How it works in practice

Find the list:

Select the needed one:

Apply it:

Of course, the Jira task describes what needs to be done and Figma shows how it should look, but from a code perspective, there are always nuances: a bit of refactoring here, rewriting an entire section there, fixing this little thing on the side, doing something a bit different than asked because… you know how it goes — and a whole lot more.

Code review is performed so that the author gets a second opinion on the chosen solution, increases the chances of catching bugs and issues early, and fosters knowledge sharing within the team.

Make your colleagues’ lives easier — briefly explain what you did and why.

About the example

In my example, the subgroups team-1 and team-2 of the backend_developers group are used. They are assigned as reviewers and get notified. Also, right after creation the MR author is assigned automatically and the labels Review and Backend are applied without extra clicks.

Template name used in the example: Backend-ALL.md

Code snippet:

* Jira tasks: TASK-
* Reviewers: @backend_developers/team-1 @backend_developers/team-2

### What

### Why
-
-

/assign_reviewer @backend_developers/team-1 @backend_developers/team-2
/assign me
/label ~Review ~Backend

Many team members have personal filters set up based on team labels.

Tips and tricks

Use labels — they make it easy to filter merge requests by teams, domains or change types. Color-coded labels simplify visual navigation: even a quick glance is enough to understand what the MR relates to.

Be careful with the filename — it will be used as the template name in the dropdown list. The name should be concise and clearly reflect the template’s purpose.

GitLab generates the list of available templates from the default branch (main or master). So, if you add a template in a separate branch and don’t see it in the list, don’t worry. After merging into the default branch, the template will appear.