Skip to main content
Back to Blog

GitLab Merge Request Template: Examples & Setup Guide

·12 min read·

A GitLab merge request template is a markdown file that pre-fills the description of new merge requests. Save it in .gitlab/merge_request_templates/ on your default branch. Name it Default.md and GitLab applies it to every new merge request automatically. Any other file name shows up in the Choose a template dropdown. Templates work on every GitLab tier, including Free.

The rules in one place:

  • Folder: .gitlab/merge_request_templates/ (issue templates go in .gitlab/issue_templates/).
  • Extension: .md only.
  • Branch: the file must be on the project's default branch.
  • Default template: a file named Default.md (case-insensitive).

Here is a default template you can copy right now:

## What does this MR do?

<!-- One or two sentences: what changes, and why. -->

## Related issues

Closes #

## Type of change

- [ ] New feature
- [ ] Bug fix
- [ ] Refactoring (no functional change)
- [ ] Documentation
- [ ] CI/CD or infrastructure

## How to test

1.
2.

## Screenshots or recordings

<!-- For UI changes. Delete this section if not needed. -->

## Checklist

- [ ] Self-reviewed the diff
- [ ] Tests added or updated
- [ ] Pipeline passes
- [ ] Documentation updated if needed

The rest of this guide covers setup step by step, four more templates (feature, bug, hotfix and AI-assisted), quick actions that add labels and assignees automatically, template variables, group-level templates, and what to check when a template doesn't show up. Using GitHub instead? See the GitHub pull request template guide.


How to Add a Merge Request Template in GitLab

  1. In your repository, create the folder .gitlab/merge_request_templates/.
  2. Add a markdown file for each template, for example Default.md, Feature.md and Bug.md. The file name, without .md, is the name people see in the dropdown.
  3. Commit the files and merge them into the default branch (usually main).
  4. Open a new merge request. Default.md is filled in already; the others are in the Choose a template dropdown above the description.

From the command line, with the templates from this guide:

mkdir -p .gitlab/merge_request_templates
cd .gitlab/merge_request_templates
curl -o Default.md https://gitmore.io/blog/templates/gitlab-mr-template-default.md
curl -o Feature.md https://gitmore.io/blog/templates/gitlab-mr-template-feature.md
curl -o Bug.md https://gitmore.io/blog/templates/gitlab-mr-template-bugfix.md
cd -
git add .gitlab/merge_request_templates
git commit -m "Add merge request templates"
git push

The resulting layout:

.gitlab/
├── merge_request_templates/
│   ├── Default.md      # applied to every new MR
│   ├── Feature.md
│   ├── Bug.md
│   └── Hotfix.md
└── issue_templates/
    └── Bug report.md

Choosing a template when you create a merge request

Unlike GitHub, GitLab has a real template picker. When you create or edit a merge request, open the Choose a template dropdown next to the description. If the description already has text, GitLab asks you to confirm with Apply template. To go back, open the dropdown and select Reset template.


How to Set a Default Merge Request Template

There are two ways to make a template apply to every new merge request without anyone picking it:

  • A Default.md file in .gitlab/merge_request_templates/. Works on every tier, lives in the repository and is reviewed like code. This is what most teams should use.
  • The project setting (Premium and Ultimate): go to Settings > Merge requests, fill in Default description template for merge requests and select Save changes.

If more than one default exists, GitLab picks the first one it finds, in this order:

PrioritySourceTier
1Template in the project settingsPremium, Ultimate
2Default.md from the parent groupPremium, Ultimate
3Default.md in the project repositoryAll tiers

Common surprise: your project's Default.md is ignored if someone filled in the default template in the project settings. Clear the setting, or put the template there instead.


GitLab Merge Request Template Examples

Four more templates for the most common kinds of change. Each one ends with quick actions that label the merge request and assign it to the author. Delete those lines if your project doesn't use these labels.

Feature template

For new functionality. It asks for the decisions a reviewer can't see in the diff: trade-offs, migrations and the feature flag.

## Feature summary

<!-- What does this feature do, who is it for, and why now? -->

## Related issues

Closes #

## Implementation notes

<!-- Key technical decisions, trade-offs, alternatives you rejected. -->

## API or schema changes

- [ ] None
- [ ] API change (describe below)
- [ ] Database migration included (reversible: yes / no)

## Feature flag

- [ ] Not behind a flag
- [ ] Behind flag: `flag_name`

## How to test

1.
2.
3.

## Screenshots or recordings

## Checklist

- [ ] Self-reviewed the diff
- [ ] Unit and integration tests added
- [ ] Pipeline passes
- [ ] Documentation and changelog updated
- [ ] Backwards compatible, or migration plan described above

/label ~"type::feature"
/assign me

Bug fix template

A good bug fix explains the root cause, not only the symptom, and shows the reviewer how to check it:

## Bug

<!-- What was broken? Expected vs actual behaviour. -->

**Expected:**

**Actual:**

## Related issues

Closes #

## Root cause

<!-- Why did it happen? Be specific. -->

## Fix

<!-- What this MR changes, and why it fixes the root cause rather than the symptom. -->

## How to verify

1. Steps to reproduce before the fix:
2. Expected result after the fix:

## Regression risk

<!-- What else could this change affect? -->

## Checklist

- [ ] Regression test added
- [ ] Pipeline passes
- [ ] Verified the reproduction steps above

/label ~"type::bug"
/assign me

Templates in place?

Let your merge requests write the weekly update

Gitmore reads merged MRs and commits from GitLab.com or self-hosted GitLab and sends a plain-English summary to Slack or email. Free plan, no credit card.

Try Gitmore free

Hotfix template

Short on purpose. During an incident, the reviewer needs severity, scope and a way back:

## Hotfix summary

<!-- One line: what is broken in production and what this changes. -->

## Severity

- [ ] S1 - Outage or data loss
- [ ] S2 - Major feature broken for many users
- [ ] S3 - Significant issue for a subset of users

## Incident

<!-- Link to the incident issue, alert or status page. -->

## Root cause

## Fix

<!-- Keep it minimal. No unrelated changes. -->

## Rollback plan

- [ ] Safe to revert this MR directly
- [ ] Needs extra steps (describe)

## Checklist

- [ ] Tested against the reproduction case
- [ ] Verified on staging (if possible)
- [ ] Second engineer reviewed
- [ ] Follow-up issue for the post-incident review

/label ~"type::bug" ~"priority::1"
/assign me

AI-assisted change template

More merge requests are now written largely by coding agents such as Claude Code, Cursor, Copilot or GitLab Duo. The diff looks the same either way, so reviewers can't tell how closely a human read it. This template asks the author to say which tool was used and to confirm the checks agents tend to skip:

## What does this MR do?

<!-- One or two sentences: what changes, and why. -->

## Related issues

Closes #

## AI assistance

- [ ] No AI tool used
- [ ] AI-assisted (autocomplete or chat suggestions)
- [ ] Mostly written by an AI coding agent

**Tool(s):** <!-- e.g. GitLab Duo, Claude Code, Cursor, Copilot, Codex -->

## Human review of AI-written code

- [ ] I read and understand every changed line
- [ ] I checked edge cases and error handling the agent may have skipped
- [ ] No secrets, credentials or customer data were sent to the AI tool
- [ ] New dependencies were checked (they exist, are maintained, and licences are OK)

## How to test

1.
2.

## Checklist

- [ ] Tests added or updated (not only generated by the same agent)
- [ ] Pipeline passes

/label ~"ai-assisted"

A checkbox depends on people filling it in honestly. To see which merge requests agents actually wrote, from commit trailers and bot authors rather than self-reporting, see how to measure AI coding agents.

Download all templates

Save them in .gitlab/merge_request_templates/ with the file names shown.

Want a stricter checklist for authors and reviewers? The pull request checklist explains each item and has a GitLab Default.md version.


Quick Actions in Merge Request Templates

GitLab runs quick actions written in a template when the merge request is created, so a template can set labels, assignees, reviewers and the milestone as well as the description. Put each one on its own line at the end of the template:

/label ~"type::feature" ~"needs-review"
/assign me
/assign_reviewer @tech-lead
/milestone %"2026.12"
/draft
  • Quick actions only run if the person creating the merge request has permission to do that action. For example, someone who can't set labels gets the merge request without the label.
  • GitLab removes the quick action lines from the saved description, so they never clutter the merge request.
  • Labels and milestones must already exist in the project or group.
  • Don't copy /cc from older examples. GitLab removed it in 18.3. Use /assign_reviewer or a plain @mention instead.

GitLab Merge Request Template Variables

Unlike GitHub, GitLab supports variables in merge request templates. They are filled in when the merge request is saved for the first time. The catch: variables only work in the default template, not in templates picked from the dropdown.

VariableBecomes
%{source_branch}The branch being merged
%{target_branch}The branch it merges into
%{closes_issue}A closing reference to the issue linked to the branch
%{first_commit}The full message of the first commit
%{first_multiline_commit}The first commit message that has more than one line
%{first_multiline_commit_description}The body of that commit, without its title
%{all_commits}The messages of all commits in the merge request
%{co_authored_by}Co-authored-by trailers for every commit author

A Default.md that uses them, so the author starts from the commit history instead of an empty box:

## What does this MR do?

%{first_multiline_commit_description}

## Related issues

%{closes_issue}

## Commits

%{all_commits}

## How to test

1.

<!-- %{source_branch} → %{target_branch} -->

Merge commit and squash commit messages have their own templates with a different set of variables (such as %{approved_by} and %{merged_by}), set in Settings > Merge requests. They control the commit written to the target branch, not the merge request description.


Share Templates Across a GitLab Group

Copying the same templates into every repository goes out of date fast. On Premium and Ultimate you can keep them in one project and share them with the whole group:

  1. Create a project in the group (for example templates) and add your files to its .gitlab/merge_request_templates/.
  2. As a group Owner, go to the group's Settings > General, expand Templates, select that project and save.
  3. Projects that are direct children of the group now see the shared templates in the dropdown, next to their own.

GitLab Self-Managed and Dedicated can also set instance-wide templates through an instance template repository. On the Free tier, keep one source repository for the templates and copy them into each project with the commands above.


Merge Request Template Not Showing? Check These

  1. Wrong branch. Templates are read from the default branch only. A template that exists only on your feature branch won't appear, even in that branch's own merge request.
  2. Wrong folder name. It is .gitlab/merge_request_templates/ (plural, underscores, starting with a dot), not merge_request_template or .github/.
  3. Wrong extension. Only .md files are picked up.
  4. A project setting overrides Default.md. On Premium and Ultimate, a default template set in Settings > Merge requests wins over the file (see the priority table above).
  5. Variables printed literally. If you see %{all_commits} in the description, the template was picked from the dropdown. Variables only work in the default template.
  6. Quick actions ignored. The author lacks permission for that action, or the label or milestone doesn't exist.
  7. Created from the CLI or API. Tools that send their own description, such as glab mr create --description, replace the template. Run glab mr create without it, or paste the template into the description yourself.

Merge Request vs Pull Request

They are the same thing with different names. GitLab calls a request to merge one branch into another a merge request (MR); GitHub and Bitbucket call it a pull request (PR). The templates differ only in where they live and what the platform adds on top:

GitLabGitHub
File location.gitlab/merge_request_templates/*.md.github/pull_request_template.md
Choosing a templateDropdown in the form?template= URL parameter
VariablesYes, in the default templateNo (needs a GitHub Action)
Labels and assigneesQuick actions in the templateNot from the template
Shared defaultsGroup or instance templates (Premium)Organization .github repo

For Bitbucket and a platform-neutral version, see the pull request template guide.


Better Merge Requests, Better Reports

A template pays off twice. Reviewers get context, and your merge request history becomes something you can actually report on. When every MR says what it does, which issue it closes and what kind of change it is, a weekly summary can say "shipped the new billing page, fixed two checkout bugs, upgraded the CI runners" instead of "14 MRs merged".

That is what Gitmore for GitLab does: it reads merged merge requests and commits from GitLab.com or self-hosted GitLab and sends a plain-English report to Slack or email, including which changes came from AI coding agents. See a sample report.


Frequently Asked Questions

Where do I put a merge request template in GitLab?

In .gitlab/merge_request_templates/ in your repository, as a .md file, on the default branch.

How do I make a merge request template the default in GitLab?

Name the file Default.md (any capitalisation) and GitLab applies it to every new merge request. On Premium and Ultimate you can instead set it in Settings > Merge requests > Default description template for merge requests, which takes priority over the file.

Can I have multiple merge request templates in GitLab?

Yes. Every .md file in the folder becomes an option in the Choose a template dropdown when you create or edit a merge request.

Are merge request templates available on GitLab Free?

Yes. Project templates, Default.md, variables and quick actions work on every tier. The project-settings default and group or instance templates need Premium or Ultimate.

Can a GitLab template add labels or assign reviewers?

Yes, with quick actions such as /label ~bug, /assign me and /assign_reviewer @name, each on its own line. They run when the merge request is created, if the author has permission.

Do issue templates work the same way?

Yes. Put them in .gitlab/issue_templates/ instead. The same rules apply: .md files, default branch, and Default.md for the default.

Gitmore

Stop writing status updates by hand

Gitmore turns your commits and pull requests into a clear weekly report in Slack or email, including what your AI coding agents shipped. Free to start, connects in minutes.

Start free

Explore git reporting for your platform

Know what shipped without asking

Gitmore turns your GitHub, GitLab or Bitbucket activity into a plain-English report in Slack or email. Set up in 2 minutes, free plan, no credit card required.