Merge request title templates
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed
- Status: Beta
The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.
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:
- In the left sidebar, select Search or go to and find your project.
- Select Settings > Merge requests.
- Scroll to Merge request title template.
- Enter a template using static text and supported variables. The template is limited to 100 characters.
- 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:
| Variable | Description | Output 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 |
Template examples
| Template | Result |
|---|---|
%{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 |
Title template assignment
When you create a merge request, GitLab assigns the title in this order:
- If you provide a title, GitLab uses it.
- If a title template is configured, GitLab uses the expanded template.
- 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:
- If the merge request has a single commit, the commit title.
- If the merge request has multiple commits, the title of the first commit with a multi-line commit message.
- If the source branch name starts with an issue IID followed by a hyphen, for example
123-fix-typo, the title isResolve "<your_issue_title>". - 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.