- Description templates
Introduced in GitLab 8.11.
We all know that a properly submitted issue is more likely to be addressed in a timely manner by the developers of a project.
Description templates allow you to define context-specific templates for issue and merge request description fields for your project, as well as help filter out a lot of unnecessary noise from issues.
By using the description templates, users that create a new issue or merge request can select a description template to help them communicate with other contributors effectively.
Every GitLab project can define its own set of description templates as they are added to the root directory of a GitLab project's repository.
Description templates must be written in Markdown and stored
in your project's repository under a directory named
.gitlab. Only the
templates of the default branch will be taken into account.
- Add a template to be used in every issue for a specific project, giving instructions and guidelines, requiring for information specific to that subject. For example, if you have a project for tracking new blog posts, you can require the title, outlines, author name, author social media information, etc.
- Following the previous example, you can make a template for every MR submitted with a new blog post, requiring information about the post date, frontmatter data, images guidelines, link to the related issue, reviewer name, etc.
- You can also create issues and merge request templates for different stages of your workflow, e.g., feature proposal, feature improvement, bug report, etc.
Create a new Markdown (
.md) file inside the
directory in your repository. Commit and push to your default branch.
Similarly to issue templates, create a new Markdown (
.md) file inside the
.gitlab/merge_request_templates/ directory in your repository. Commit and
push to your default branch.
Let's take for example that you've created the file
This will enable the
Bug dropdown option when creating or editing issues. When
Bug is selected, the content from the
Bug.md template file will be copied
to the issue description field. The 'Reset template' button will discard any
changes you made after picking the template and return it to its initial status.
The visibility of issues and/or merge requests should be set to either "Everyone with access" or "Only team members" in your project's Settings otherwise the template text areas won't show. This is the default behavior so in most cases you should be fine.
Go to your project's Settings and fill in the "Default description template for issues" and "Default description template for merge requests" text areas for issues and merge requests respectively. Since GitLab issues and merge request support Markdown, you can use special markup like headings, lists, etc.
After you add the description, hit Save changes for the settings to take effect. Now, every time a new issue or merge request is created, it will be pre-filled with the text you entered in the template(s).