ContextQMD
Back to Gitlabhq

Merge request title templates

doc/user/project/merge_requests/title_templates.md

19.0.04.6 KB
Original Source

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed

{{< /details >}}

{{< history >}}

  • Introduced in GitLab 18.11 with a feature flag named mr_default_title_template. Disabled by default. This feature is in beta.
  • Generally available in GitLab 19.0. Feature flag mr_default_title_template removed.

{{< /history >}}

Merge request title templates define the default title for new merge requests in a project. Use templates to standardize merge request naming conventions across your team.

Templates support variables that expand to values like the source branch name or the first commit message. Users can edit the title before creating the merge request.

Configure a merge request title template

Prerequisites:

  • You must have at least the Maintainer role for the project.

To configure a merge request title template:

  1. In the left sidebar, select Search or go to and find your project.
  2. Select Settings > Merge requests.
  3. Scroll to Merge request title template.
  4. Enter a template using static text and supported variables. The template is limited to 100 characters.
  5. Select Save changes.

To remove the template and restore the default behavior, clear the template field and select Save changes.

Supported variables

Title templates support the following variables:

VariableDescriptionOutput example
%{source_branch}The name of the source branch.my-feature-branch
%{target_branch}The name of the target branch.main
%{title_from_branch}The source branch name converted to a human-readable format. Hyphens and underscores are replaced with spaces.My feature branch
%{first_commit_title}The subject (first line) of the first commit in the merge request.Update README.md
%{issue_id}The IID of the issue linked through the source branch name (for example, 123 from 123-fix-bug). Blank if no issue is detected.123
%{issue_title}The title of the issue linked through the source branch name. Blank if no issue is detected.Fix login bug

Template examples

TemplateResult
%{source_branch}my-feature-branch
%{title_from_branch}My feature branch
%{first_commit_title}Update README.md
Draft: %{title_from_branch}Draft: My feature branch
[%{source_branch}] %{first_commit_title}[my-feature-branch] Update README.md
Resolve %{issue_id} "%{issue_title}"Resolve 123 "Fix login bug"

Title template assignment

When you create a merge request, GitLab assigns the title in this order:

  1. If you provide a title, GitLab uses it.
  2. If a title template is configured, GitLab uses the expanded template.
  3. If no template is set, GitLab uses the default title behavior.

Default title behavior

When no title template is configured and you don't provide a title, GitLab generates the title by checking these conditions in order:

  1. If the merge request has a single commit, the commit title.
  2. If the merge request has multiple commits, the title of the first commit with a multi-line commit message.
  3. If the source branch name starts with an issue IID followed by a hyphen, for example 123-fix-typo, the title is Resolve "<your_issue_title>".
  4. Otherwise, the source branch name, with hyphens and underscores replaced by spaces.

If the merge request has no commits, or you mark it as a draft, GitLab prepends Draft: to the title.