If you don’t code 🤓
For users who often use GitLab to log issues of the same nature, creating standardised issue templates will help to save you some time when you are writing a new issue. It is straight-froward, and you can leave mental energy for other problems at work ;)
It’s also useful for onboarding of new team members, where they can follow a standardized template, and easily orientate themselves into the team processes.
And the best thing is, the templates can be edited anytime when the team feels that there’s a need to improve on it.
Follow the little blue man in the screenshots and you will have the issue templates up in no time!
To create a default template for all issue cards:
- Go to your project group page, click on the specific sub-group project you want to add the issue template for. (There isn’t a place where you can add the issue templates once for every sub-group, so you got to repeat this process a few times ;))
2. On the left navigation, hover on Settings, click General. Look for “Default issue template” section, and click Expand button.
3. Type what you want to see in the template into the description box. It supports markdown, so if you want to bold the word, remember to type **word**.
4. Go on and create a new issue, you should see the template now!
To create various types of templates for issue cards
- Similarly, go to the project group page you want to work on, click on the specific sub-group project you want to add the issue template for.
2. On the project page left navigation panel, hover on Repository, and click Files.
3. On the repository files page, ensure you are on the default branch. How to know which is your default branch? You can ask your developer ;p
Or, you can click on Branches under Repository, there will be a label “default” beside the default branch name. In my example, master is the default branch.
There will be a series of folders, likely to be created by your developers. Look for the folder named “.gitlab”. If there isn’t such a folder already, next step will show you how to create.
4. On the right of the project name, click on the “+” button. There will be a dropdown list of items, select “New directory”.
5. On the pop-up form to create new directory, input directory name as “.gitlab” — Note: Do not alter this to any other names, it must be exact, with the period in front of the word gitlab. For commit message, you can write anything you like ;p
6. You would see that you have successfully created a new folder directory “.gitlab”. From here, you will create another folder under the “.gitlab” folder. Click on the “+” button. There will be a dropdown list of items, select “New directory”.
7. On the pop-up form to create new directory, input directory name as “issue_templates” — Note: Do not alter this to any other names, it must be exact ;)
8. Once this new folder “issue_templates” is created, we are good to start creating issue templates! Click on the “+” button. There will be a dropdown list of items, select “New file”.
9. On the New file page, it’s where you can name the template and create the template style.
For template name, there’s 2 things to take note
i) Always put underscore in place of spaces
ii) Always end it with “.md” (md means markdown)
So a sample template name will be “bug_report.md”
For template style, you can create it with markdowns. For example, my bug report template will have the following:
i) Steps to replicate
ii) Current (behaviour)
iii) Expected (behaviour)
For commit message, you can write anything, it’s for your own reference.
10. Click Commit Changes button, and there, your issue template is created!
11. Go and create a new issue, you will notice that there’s a new Description down-down field right below Title. The new template you added should be there for selection. Select it and ta-da — the template is populated. C’mon, you deserve a cheer!
12. When you need to add new templates, repeat the same. Go to Repository > Files, look for .gitlab folder, click issue_templates folder, click New file (See Step 8)
13. When you need to edit existing templates, click into the template you wish to edit, click Edit button, make the changes and click Commit Changes. The template will be saved!
You can find some super useful templates here: https://gitlab.com/gitlab-org/gitlab/-/tree/master/.gitlab/issue_templates
I hope this tutorial is useful for users who need more help on issue template creation! And a shout-out request to GitLab — templates for the comments section would be really useful too ;)
