• Create an issue template
• Create a merge request template
• Use the templates
  • Supported variables in merge request templates
  • Set instance-level description templates
  • Set group-level description templates
  • Set a default template for merge requests and issues
    • Priority of default description templates
• Example description template

Description templates

You can define templates to use as descriptions for your issues and merge requests.

You can define these templates in a project, group, or instance. Projects inherit the templates defined at a higher level.

You might want to use these templates:

• For different stages of your workflow, for example, feature proposal, feature improvement, or a bug report.
• For every issue or merge request for a specific project, so the layout is consistent.
• For a Service Desk email template.

For description templates to work, they must be:

• Saved with the .md extension.
• Stored in your project’s repository in the .gitlab/issue_templates or .gitlab/merge_request_templates directory.
• Be present on the default branch.

Create an issue template

Create a new Markdown (.md) file inside the .gitlab/issue_templates/ directory in your repository.

To create an issue description template:

1. On the left sidebar, select Search or go to and find your project.
2. Select Code > Repository.
3. Next to the default branch, select .
4. Select New file.
5. Next to the default branch, in the File name text box, enter .gitlab/issue_templates/mytemplate.md, where mytemplate is the name of your issue template.
6. Commit to your default branch.

To check if this has worked correctly, create a new issue and see if you can find your description template in the Choose a template dropdown list.

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. Unlike issue templates, merge requests have additional inheritance rules that depend on the contents of commit messages and branch names.

To create a merge request description template for a project:

1. On the left sidebar, select Search or go to and find your project.
2. Select Code > Repository.
3. Next to the default branch, select .
4. Select New file.
5. Next to the default branch, in the File name text box, enter .gitlab/merge_request_templates/mytemplate.md, where mytemplate is the name of your merge request template.
6. Commit to your default branch.

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.

Use the templates

When you create or edit an issue or a merge request, it shows in the Choose a template dropdown list.

To apply a template:

1. Create or edit an issue or a merge request.
2. Select the Choose a template dropdown list.
3. If the Description text box hasn’t been empty, to confirm, select Apply template.
4. Select Save changes.

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.

Supported variables in merge request templates

When you save a merge request for the first time, GitLab replaces these variables in your merge request template with their values:

Set instance-level description templates

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.

Set group-level description templates

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:

• You must have the Owner role for the group.
• The project must be a direct child of the group.

To re-use templates you’ve created:

1. On the left sidebar, select Search or go to and find your group.
2. Select Settings > General.
3. Expand Templates.
4. From the dropdown list, select your template project as the template repository at group level.
5. Select Save changes.

You might also be interested in templates for various file types in groups.

Set a default template for merge requests and issues

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:

• On your project’s left sidebar, select Settings > General and expand Visibility, project features, permissions. Ensure issues or merge requests are set to either Everyone with access or Only Project Members.

To set a default description template for merge requests, either:

• In GitLab 14.8 and later, create a merge request template named Default.md (case insensitive) and save it in .gitlab/merge_request_templates/. This doesn’t overwrite the default template if one has been set in the project settings.

• Users on GitLab Premium and Ultimate: set the default template in project settings:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Settings > Merge requests.
  3. In the Default description template for merge requests section, fill in the text area.
  4. Select Save changes.

To set a default description template for issues, either:

• In GitLab 14.8 and later, create an issue template named Default.md (case insensitive) and save it in .gitlab/issue_templates/. This doesn’t overwrite the default template if one has been set in the project settings.

• Users on GitLab Premium and Ultimate: set the default template in project settings:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Settings > General.
  3. Expand Default description template for issues.
  4. Fill in the text area.
  5. Select Save changes.

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.

Priority of default description templates

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:

1. Template set in project settings.
2. Default.md (case insensitive) from the parent group.
3. 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.

Example description template

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.

Here is an example of a bug report template:

## Summary

(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