doc/user/project/description_templates.md
{{< details >}}
{{< /details >}}
{{< history >}}
work_item_epics. Enabled by default. Introduced in beta.work_item_epics removed.{{< /history >}}
Description templates standardize and automate how issues and merge requests are created in GitLab.
Description templates:
You can define templates to use as descriptions for your:
Projects inherit templates from their group and instance.
Templates must be:
.md extension..gitlab/issue_templates or .gitlab/merge_request_templates directory.Create a new description template as a Markdown (.md) file inside the .gitlab/issue_templates/ directory in your repository.
To create a work item description template:
.gitlab/issue_templates/mytemplate.md,
where mytemplate is the name of your template.To check if this has worked correctly:
Similarly to issue templates, create a new Markdown (.md) file inside the
.gitlab/merge_request_templates/ directory in your repository.
Unlike issue templates, merge requests have additional inheritance rules that depend on the contents
of commit messages and branch names.
For more information, see creating merge requests.
To create a merge request description template for a project:
.gitlab/merge_request_templates/mytemplate.md,
where mytemplate is the name of your merge request template.To check if this has worked correctly, create a new merge request and see if you can find your description template in the Choose a template dropdown list.
When you create or edit an issue or a merge request, it shows in the Choose a template dropdown list.
To apply a template:
When you select a description template, its content is copied to the description text box.
To discard any changes to the description you've made after selecting the template: expand the Choose a template dropdown list and select Reset template.
[!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. Read more about creating issues using a URL with prefilled values.
{{< history >}}
{{< /history >}}
[!note] This feature is available only for the default template.
When you save a merge request for the first time, GitLab replaces these variables in your merge request template with their values:
| Variable | Description | Output example |
|---|---|---|
%{all_commits} | Messages from all commits in the merge request. Limited to 100 most recent commits. Skips commit bodies exceeding 100 KiB and merge commit messages. | * Feature introduced |
This commit implements feature
Changelog:added
* Bug fixed
* Documentation improved
This commit introduced better docs. |
| %{co_authored_by} | Names and emails of commit authors in a Co-authored-by Git commit trailer format. Limited to authors of 100 most recent commits in merge request. | Co-authored-by: Zane Doe <[email protected]>
Co-authored-by: Blake Smith <[email protected]> |
| %{first_commit} | Full message of the first commit in merge request diff. | Update README.md |
| %{first_multiline_commit} | Full message of the first commit that's not a merge commit and has more than one line in message body. Merge request title if all commits aren't multiline. | Update README.md
Improved project description in readme file. |
| %{first_multiline_commit_description} | Description (without the first line/title) of the first commit that's not a merge commit and has more than one line in message body. | Improved project description in readme file. |
| %{source_branch} | The name of the branch being merged. | my-feature-branch |
| %{target_branch} | The name of the branch that the changes are applied to. | main |
{{< details >}}
{{< /details >}}
You can set a description template at the instance level for issues and merge requests by using an instance template repository. You can also use the instance template repository for file templates.
You might also be interested in project templates that you can use when creating a new project in the instance.
{{< details >}}
{{< /details >}}
With group-level description templates, you can select a project within the group to store your templates. Then, you can access these templates in other projects in the group. As a result, you can use the same templates in issues and merge requests in all the group's projects.
Prerequisites:
To re-use templates you've created:
You might also be interested in templates for various file types in groups.
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.
Prerequisites:
To set a default description template for merge requests, either:
Create a merge request template named Default.md (case-insensitive)
and save it in .gitlab/merge_request_templates/.
The Default.md template does not take priority over the default template set in project settings.
For more information, see priority of default description templates.
Users on GitLab Premium and Ultimate: set the default template in project settings:
To set a default description for work items, either:
Create a description template named Default.md (case-insensitive)
and save it in .gitlab/issue_templates/.
The Default.md template does not take priority over the default description set in project settings.
For more information, see priority of default description templates.
Users on GitLab Premium and Ultimate: set the default template in project settings:
Because GitLab merge request and issues support Markdown, you can use it to format headings, lists, and so on.
You can also provide issues_template and merge_requests_template attributes in the
Projects REST API to keep your default issue and merge request templates up to date.
When you set issue description templates in various places, they have the following priorities in a project. The ones higher up override the ones below:
Default.md (case-insensitive) from the parent group.Default.md (case-insensitive) from the project repository.Merge requests have additional inheritance rules that depend on the contents of commit messages and branch names.
We use description templates for issues and merge requests in the
.gitlab folder of the
GitLab project, which you can refer to for some examples.
[!note] It's possible to use quick actions 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:
## Summary
<!-- HTML comments are not displayed -->
(Summarize the bug encountered concisely)
## Steps to reproduce
(How one can reproduce the issue - this is very important)
## Example Project
(If possible, 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 - 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