Group Level Templates

Welcome to Tanuki Tuesday, where I look at the features offered by GitLab.

My very first Tanuki Tuesday post in 2021 was Issue Templates, and I have also covered Merge Request Templates. It seems fitting, therefore, that my first post of 2022 is how to use those between projects.

When your organisation or side project gets beyond one or two repositories, you are likely to want to standardise the process for raising issues or creating merge requests. This could be done by copying the templates from one project to another, or using Git submodules to share a repository. Both options run into issues pretty quickly.

Please note, this is a premium feature and only available to those with either of the paid subscriptions.

Possible Options

If you copy and paste the templates into each project you need to update every project whenever you make a change to the template. Doesn't matter if it's a typo or an entire process change - it's a lot of overhead to update. It also violates the DRY principle of coding - Don't Repeat Yourself.

Using Git submodules doesn't work out any better. Firstly, it wouldn't be a single submodule for the .gitlab folder, it would need two modules (and therefore repositories) - one each for issue_templates/ and merge_request_templates/. Then, not only do you have two repositories to maintain with changes, you then have to update each individual project repository with the latest hash of each template repository to get the changes. I've not actually tried this method, but I suspect it would not work anyway. With Git submodules, the files for the submodule repository are not copied into your local repository. Instead, there is a file with a commit hash to indicate what to check our during a recursive clone. The result is the repository wouldn't have the files it needs to use as templates.

Group Templates

Instead of copying files into every repository, or hoping that Git submodules are going to solve the problem, there is an easier way!

At the group level, create a new, blank repository (populate it with a README if you want). Clone that repository, and create the .gitlab folder. You can create the issue_templates and merge_request_tempaltes folders as needed. Within those folders, create any templates you wish to share between projects.

Once the templates are committed to the repository, go to the group settings > General > Templates. From there you can select the repository you want to use for the templates. In the screenshot below, I've deliberately stopped prior to the name of the repository I use as it has my employer's namespace as part of it.

Once you have pressed the "save changes" button, the templates are available to use in your issues or merge requests, depending on what you created.

What about project templates?

Project level templates are still known and understood by GitLab. If you have both, the Group templates are shown first (under a heading of Group <namespace>), with project templates appearing after, under a heading of Project Templates. This provides the flexibility of both generic templates to be shared to save repetition, and also more specific templates as and when they are needed.

For instance, I have Bug and Feature Request templates shared by the group templates which are available across all projects within the group. I then have a specific Firewall Change template within the Terraform project, which controls the creation of firewall rules. That template makes no sense if it's in a project which has nothing to do with firewalls.

So it all works exactly the same?

Well, not quite!

Some people make use of URL shortcuts for defaulting templates e.g. https://example.gitlab.com/namespace/project/-/issues/new?issuable_template=Bug That will default the template to the Bug template. If you have a group level template and a project level template with the same name then you may get behaviour you deem undesirable. In this case, GitLab will pick the group level template over the project level one. I've not (yet) found a way to override it to the project one.

This is a fairly extreme edge case (I think), but something to be aware of all the same.

Right, but nothing is different from a year ago!

You'd think so. You'd think that issue and merge request templates are that simple that there's nothing which can be done with them. GitLab and its wonderful community have other ideas.

With the templates feature from 2021, the user has to select a template each and every time they create a new issue or merge request (with the exception of when using a URL with the issuable_template parameter.

There is a in-progress issue within GitLab to allow templates to be created with the name default.md, which will pre-populate the description with the content of that template. The documentation for this feature only mentions this working on project templates (at the time of writing). Group level templates can be used in the same way. Creating a default.md template in your group level template repository uses the group level template as the default, and therefore across your projects.

This new feature was scheduled for release in GitLab 14.7, but testing identified a regression which caused issues for a lot of people. This is being worked on, but shows how committed GitLab and the community are to reducing cognitive load and improving workflow for everyone using the product. I look forward to seeing that feature make a solid resurgance.

Conclusion

Group level templates are a great feature if you have that option available. Building a level of standardisation into issues within your organisation will hopefully drive higher quality reports consistently, and improve turn-around time for resolving the issues. Hopefully.

I don't think it's a feature which is likely to cause people to upgrade from free to a paid subscription by itself. But when put forward as part of a business case with other premium features like scoped labels, the time saving and consistency might help open a whole world of other features for you.

Updates:

This article was updated to correct the statement that the default.md templates are available from 14.7