2020-05-26 23:08:26 -04:00
---
stage: Plan
group: Project Management
2020-11-26 01:09:20 -05:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-05-26 23:08:26 -04:00
---
2016-08-17 06:27:14 -04:00
# Description templates
2021-01-13 22:10:47 -05:00
>[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4981) in GitLab 8.11.
2016-08-17 06:27:14 -04:00
2019-05-05 11:37:18 -04:00
We all know that a properly submitted issue is more likely to be addressed in
a timely manner by the developers of a project.
2021-01-13 22:10:47 -05:00
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.
## Overview
2016-08-17 06:27:14 -04:00
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 ](../markdown.md ) and stored
in your project's repository under a directory named `.gitlab` . Only the
2020-12-07 13:10:36 -05:00
templates of the default branch are taken into account.
2016-08-17 06:27:14 -04:00
2021-01-13 22:10:47 -05:00
## Use-cases
2019-05-05 11:37:18 -04:00
- Add a template to be used in every issue for a specific project,
2019-06-25 00:34:55 -04:00
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
2020-03-31 23:07:57 -04:00
title, outlines, author name, author social media information, and so on.
2019-05-05 11:37:18 -04:00
- Following the previous example, you can make a template for every MR submitted
2020-05-20 02:08:06 -04:00
with a new blog post, requiring information about the post date, front matter data,
2020-03-31 23:07:57 -04:00
images guidelines, link to the related issue, reviewer name, and so on.
2019-05-05 11:37:18 -04:00
- You can also create issues and merge request templates for different
2020-03-31 23:07:57 -04:00
stages of your workflow, for example, feature proposal, feature improvement, or a bug report.
2019-05-05 11:37:18 -04:00
2021-01-13 22:10:47 -05:00
## Creating issue templates
2016-08-17 06:27:14 -04:00
Create a new Markdown (`.md`) file inside the `.gitlab/issue_templates/`
directory in your repository. Commit and push to your default branch.
2020-05-19 14:08:11 -04:00
To create a Markdown file:
1. Click the `+` button next to `master` and click **New file** .
1. Add the name of your issue template to the **File name** text field next to `master` .
2020-10-02 14:08:56 -04:00
Make sure that your file has the `.md` extension, for
example `feature_request.md` or `Feature Request.md` .
2020-05-19 14:08:11 -04:00
1. Commit and push to your default branch.
2020-12-07 13:10:36 -05:00
If you don't have a `.gitlab/issue_templates` directory in your repository, you need to create it.
2020-05-19 14:08:11 -04:00
To create the `.gitlab/issue_templates` directory:
1. Click the `+` button next to `master` and select **New directory** .
1. Name this new directory `.gitlab` and commit to your default branch.
1. Click the `+` button next to `master` again and select **New directory** .This time, n
1. Name your directory `issue_templates` and commit to your default branch.
2020-11-08 22:09:03 -05:00
To check if this has worked correctly, [create a new issue ](issues/managing_issues.md#create-a-new-issue )
2020-05-19 14:08:11 -04:00
and see if you can choose a description template.
2021-01-13 22:10:47 -05:00
## Creating merge request templates
2016-08-17 06:27:14 -04:00
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.
2021-01-13 22:10:47 -05:00
## Using the templates
2016-08-17 06:27:14 -04:00
2016-08-17 08:27:18 -04:00
Let's take for example that you've created the file `.gitlab/issue_templates/Bug.md` .
2020-12-07 13:10:36 -05:00
This enables the `Bug` dropdown option when creating or editing issues. When
`Bug` is selected, the content from the `Bug.md` template file is copied
to the issue description field. The **Reset template** button discards any
changes you made after picking the template and returns it to its initial status.
2016-08-17 06:27:14 -04:00
2020-12-07 22:09:37 -05:00
NOTE:
2021-01-13 22:10:47 -05:00
You can create short-cut links to create an issue using a designated template. For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal` .
2020-09-30 14:09:52 -04:00
2016-08-17 06:27:14 -04:00
![Description templates ](img/description_templates.png )
2021-01-13 22:10:47 -05:00
## Setting a default template for merge requests and issues **(STARTER)**
2019-05-05 11:37:18 -04:00
2021-01-13 22:10:47 -05:00
> - This feature was introduced before [description templates](#overview) and is available in [GitLab Starter](https://about.gitlab.com/pricing/). It can be enabled in the project's settings.
> - Templates for issues were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28) in GitLab EE 8.1.
> - Templates for merge requests were [introduced](https://gitlab.com/gitlab-org/gitlab/commit/7478ece8b48e80782b5465b96c79f85cc91d391b) in GitLab EE 6.9.
2019-05-05 11:37:18 -04:00
The visibility of issues and/or merge requests should be set to either "Everyone
2019-08-15 02:03:09 -04:00
with access" or "Only Project Members" in your project's **Settings / Visibility, project features, permissions** section, otherwise the
2020-12-07 13:10:36 -05:00
template text areas don't show. This is the default behavior, so in most cases
2019-05-05 11:37:18 -04:00
you should be fine.
2020-03-31 23:07:57 -04:00
1. Go to your project's **Settings** .
1. Click **Expand** under the **Merge requests** header.
1. Fill in the **Default description template for merge requests** text area.
1. Click **Expand** under **Default issue template** .
1. Fill in the **Default description template for issues** text area.
Since GitLab merge request and issues support [Markdown ](../markdown.md ), you can use it to format
headings, lists, and so on.
2019-05-05 11:37:18 -04:00
2019-08-15 02:03:09 -04:00
![Default merge request description templates ](img/description_templates_merge_request_settings.png )
2020-03-31 23:07:57 -04:00
2019-08-15 02:03:09 -04:00
![Default issue description templates ](img/description_templates_issue_settings.png )
2019-05-05 11:37:18 -04:00
After you add the description, hit **Save changes** for the settings to take
2021-01-11 19:10:42 -05:00
effect. Now, every time a new merge request or issue is created, it is
2019-05-05 11:37:18 -04:00
pre-filled with the text you entered in the template(s).
2017-09-06 04:32:31 -04:00
## Description template example
2021-01-13 22:10:47 -05:00
We make use of Description Templates for Issues and Merge Requests within the GitLab Community
Edition project. Please refer to the [`.gitlab` folder ](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab )
2020-03-31 23:07:57 -04:00
for some examples.
2017-09-06 04:32:31 -04:00
2020-12-07 22:09:37 -05:00
NOTE:
2021-01-13 22:10:47 -05:00
It's possible to use [quick actions ](quick_actions.md ) within description templates to quickly add
2020-12-07 13:10:36 -05:00
labels, assignees, and milestones. The quick actions are only executed if the user submitting
2020-03-31 23:07:57 -04:00
the issue or merge request has the permissions to perform the relevant actions.
2017-09-06 04:32:31 -04:00
2020-03-31 23:07:57 -04:00
Here is an example of a Bug report template:
2017-09-06 04:35:00 -04:00
2021-01-13 22:10:47 -05:00
```plaintext
Summary
2017-09-06 04:35:00 -04:00
(Summarize the bug encountered concisely)
2021-01-13 22:10:47 -05:00
Steps to reproduce
2017-09-06 04:35:00 -04:00
(How one can reproduce the issue - this is very important)
2021-01-13 22:10:47 -05:00
Example Project
(If possible, please create an example project here on GitLab.com that exhibits the problematic behaviour, and link to it here in the bug report)
2017-09-06 04:35:00 -04:00
2021-01-13 22:10:47 -05:00
(If you are using an older version of GitLab, this will also determine whether the bug has been fixed in a more recent version)
What is the current bug behavior?
2017-09-06 04:35:00 -04:00
(What actually happens)
2021-01-13 22:10:47 -05:00
What is the expected correct behavior?
2017-09-06 04:35:00 -04:00
(What you should see instead)
2021-01-13 22:10:47 -05:00
Relevant logs and/or screenshots
(Paste any relevant logs - please use code blocks (```) to format console output,
logs, and code as it's very hard to read otherwise.)
2017-09-06 04:35:00 -04:00
2021-01-13 22:10:47 -05:00
Possible fixes
2017-09-06 04:35:00 -04:00
(If you can, link to the line of code that might be responsible for the problem)
/label ~bug ~reproduced ~needs-investigation
/cc @project -manager
/assign @qa -tester
```