1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
|
---
stage: Plan
group: Project Management
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
---
# Description templates
We all know that a properly submitted issue is more likely to be addressed in
a timely manner by the developers of a project.
With description templates, you can define context-specific templates for issue and merge request
description fields for your project, and filter out 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](../markdown.md) and stored
in your project's repository in the `.gitlab` directory. Only the
templates of the default branch are taken into account.
To learn how to create templates for various file types in groups, visit
[Group file templates](../group/index.md#group-file-templates).
## Use cases
These are some situations when you might find description templates useful:
- You can create issues and merge request templates for different
stages of your workflow, for example, feature proposal, feature improvement, or a bug report.
- 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, and author social media information.
- Following the previous example, you can make a template for every MR submitted
with a new blog post, requiring information about the post date, front matter data,
images guidelines, link to the related issue, reviewer name, and so on.
- You can also create issues and merge request templates for different
stages of your workflow, for example, feature proposal, feature improvement, or a bug report.
- You can use an [issue description template](#create-an-issue-template) as a
[Service Desk email template](service_desk.md#new-service-desk-issues).
## Create an issue template
Create a new Markdown (`.md`) file inside the `.gitlab/issue_templates/`
directory in your repository. Commit and push to your default branch.
To create a Markdown file:
1. In a project, go to **Repository**.
1. Next to the default branch, select the **{plus}** button.
1. Select **New file**.
1. Next to the default branch, in the **File name** field, add the name of your issue template.
Make sure that your file has the `.md` extension, for
example `feature_request.md` or `Feature Request.md`.
1. Commit and push to your default branch.
If you don't have a `.gitlab/issue_templates` directory in your repository, you need to create it.
To create the `.gitlab/issue_templates` directory:
1. In a project, go to **Repository**.
1. Next to the default branch, select the **{plus}** button.
1. Select **New directory**.
1. Name this new directory `.gitlab` and commit to your default branch.
1. Next to the default branch, select the **{plus}** button.
1. Select **New directory**.
1. Name your directory `issue_templates` and commit to your default branch.
To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-a-new-issue)
and see if you can choose a description template.
## Create a merge request template
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.
## Use the templates
Let's take for example that you've created the file `.gitlab/issue_templates/Bug.md`.
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.
NOTE:
You can create shortcut links to create an issue using a designated template.
For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`.
You can set description templates at various levels:
- The entire [instance](#set-instance-level-description-templates)
- A specific [group or subgroup](#set-group-level-description-templates)
- A specific [project](#set-a-default-template-for-merge-requests-and-issues)
The templates are inherited. For example, in a project, you can also access templates set for the
instance or the project's parent groups.
### Set instance-level description templates **(PREMIUM SELF)**
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9.
> - [Deployed behind a feature flag](../feature_flags.md), disabled by default.
> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56737) in GitLab 13.11.
> - Enabled by default on GitLab.com.
> - Recommended for production use.
> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-issue-and-merge-request-description-templates-at-group-and-instance-level). **(PREMIUM SELF)**
You can set a description template at the **instance level** for issues
and merge requests.
As a result, these templates are available in all projects within the instance.
Only instance administrators can set instance-level templates.
To set the instance-level description template repository:
1. Select the **Admin Area** icon (**{admin}**).
1. Go to **Settings > Templates**.
1. From the dropdown, select your template project as the template repository at instance level.
1. Select **Save changes**.
Learn more about [instance template repository](../admin_area/settings/instance_template_repository.md).
### Set group-level description templates **(PREMIUM)**
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9.
> - [Deployed behind a feature flag](../feature_flags.md), disabled by default.
> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56737) in GitLab 13.11.
> - Enabled by default on GitLab.com.
> - Recommended for production use.
> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-issue-and-merge-request-description-templates-at-group-and-instance-level). **(PREMIUM SELF)**
With **group-level** description templates, you can store your templates in a single repository and
configure the group file templates setting to point to that repository.
As a result, you can use the same templates in issues and merge requests in all the group's projects.
To re-use templates [you've created](../project/description_templates.md#create-an-issue-template):
1. Go to the group's **Settings > General > Templates**.
1. From the dropdown, select your template project as the template repository at group level.
1. Select **Save changes**.
### Set a default template for merge requests and issues **(PREMIUM)**
In a project, you can choose a default description template for new issues and merge requests.
As a result, every time a new merge request or issue is created, it's pre-filled with the text you
entered in the template.
The visibility of issues or merge requests should be set to either "Everyone
with access" or "Only Project Members" in your project's
**Settings / Visibility, project features, permissions** section. Otherwise, the
template text areas don't show. This is the default behavior, so in most cases
you should be fine.
To set a default description template for merge requests:
1. Go to your project's **Settings**.
1. Select **Expand** under the **Merge requests** header.
1. Fill in the **Default description template for merge requests** text area.
1. Select **Save changes**.
To set a default description template for issues:
1. Select **Expand** under **Default issue template**.
1. Fill in the **Default description template for issues** text area.
Because GitLab merge request and issues support [Markdown](../markdown.md), you can use it to format
headings, lists, and so on.
[GitLab versions 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/885)
provide `issues_template` and `merge_requests_template` attributes in the
[Projects API](../../api/projects.md) to help you keep your templates up to date.
## Description template example
We use description templates for issues and merge requests in the
[`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab) of the
GitLab project, which you can refer to for some examples.
NOTE:
It's possible to use [quick actions](quick_actions.md) in description templates to quickly add
labels, assignees, and milestones. The quick actions are only executed if the user submitting
the issue or merge request has the permissions to perform the relevant actions.
Here is an example of a bug report template:
```markdown
## Summary
(Summarize the bug encountered concisely)
## Steps to reproduce
(How one can reproduce the issue - this is very important)
## Example Project
(If possible, please create an example project here on GitLab.com that exhibits the problematic
behavior, and link to it here in the bug report.
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?
(What actually happens)
## What is the expected correct behavior?
(What you should see instead)
## 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.)
## Possible fixes
(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
```
## Enable or disable issue and merge request description templates at group and instance level **(PREMIUM SELF)**
Setting issue and merge request description templates at group and instance levels
is under development but ready for production use. It is deployed behind a
feature flag that is **enabled by default**.
[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md)
can disable it.
To disable it:
```ruby
Feature.disable(:inherited_issuable_templates)
```
To enable it:
```ruby
Feature.enable(:inherited_issuable_templates)
```
The feature flag affects these features:
- Setting a templates project as issue and merge request description templates source at group level.
- Setting a templates project as issue and merge request description templates source at instance level.
|
