Pull Request Template Guide: Examples, Tips & Free Downloads
A complete guide to PR templates for GitLab, Bitbucket, and GitHub. Includes ready-to-use templates for features, bug fixes, and hotfixes with free markdown downloads.
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:
.gitlab/merge_request_templates/ (issue templates go in .gitlab/issue_templates/)..md only.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 neededThe 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.
.gitlab/merge_request_templates/.Default.md, Feature.md and Bug.md. The file name, without .md, is the name people see in the dropdown.main).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 pushThe resulting layout:
.gitlab/
├── merge_request_templates/
│ ├── Default.md # applied to every new MR
│ ├── Feature.md
│ ├── Bug.md
│ └── Hotfix.md
└── issue_templates/
└── Bug report.mdUnlike 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.
There are two ways to make a template apply to every new merge request without anyone picking it:
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.If more than one default exists, GitLab picks the first one it finds, in this order:
| Priority | Source | Tier |
|---|---|---|
| 1 | Template in the project settings | Premium, Ultimate |
| 2 | Default.md from the parent group | Premium, Ultimate |
| 3 | Default.md in the project repository | All 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.
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.
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 meA 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 meTemplates 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.
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 meMore 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.
Save them in .gitlab/merge_request_templates/ with the file names shown.
Default.md
General-purpose default, applied to every new merge request
Feature.md
New features: implementation notes, migrations, feature flags
Bug.md
Bug fixes: root cause, verification steps, regression risk
Hotfix.md
Urgent production fixes: severity, incident link, rollback plan
AI-assisted.md
Changes written with Claude Code, Cursor, Copilot or GitLab Duo
Want a stricter checklist for authors and reviewers? The pull request checklist explains each item and has a GitLab Default.md version.
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/cc from older examples. GitLab removed it in 18.3. Use /assign_reviewer or a plain @mention instead.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.
| Variable | Becomes |
|---|---|
%{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.
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:
templates) and add your files to its .gitlab/merge_request_templates/.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.
.gitlab/merge_request_templates/ (plural, underscores, starting with a dot), not merge_request_template or .github/..md files are picked up.%{all_commits} in the description, the template was picked from the dropdown. Variables only work in the default template.glab mr create --description, replace the template. Run glab mr create without it, or paste the template into the description yourself.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:
| GitLab | GitHub | |
|---|---|---|
| File location | .gitlab/merge_request_templates/*.md | .github/pull_request_template.md |
| Choosing a template | Dropdown in the form | ?template= URL parameter |
| Variables | Yes, in the default template | No (needs a GitHub Action) |
| Labels and assignees | Quick actions in the template | Not from the template |
| Shared defaults | Group or instance templates (Premium) | Organization .github repo |
For Bitbucket and a platform-neutral version, see the pull request template guide.
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.
In .gitlab/merge_request_templates/ in your repository, as a .md file, on the default branch.
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.
Yes. Every .md file in the folder becomes an option in the Choose a template dropdown when you create or edit a merge request.
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.
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.
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.
Explore git reporting for your platform
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.