diff options
Diffstat (limited to 'doc/user/project/description_templates.md')
| -rw-r--r-- | doc/user/project/description_templates.md | 32 |
1 files changed, 20 insertions, 12 deletions
diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index ffbe7447aa8..f0ced95c8eb 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -16,7 +16,7 @@ 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](service_desk.md#new-service-desk-issues). +- For a [Service Desk email template](service_desk.md#use-a-custom-template-for-service-desk-issues). For description templates to work, they must be: @@ -46,10 +46,11 @@ and see if you can find your description template in the **Choose a template** d ## 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. Commit and -push to your default branch. +`.gitlab/merge_request_templates/` directory in your repository. Unlike issue +templates, merge requests have [additional inheritance rules](merge_requests/creating_merge_requests.md) +that depend on the contents of commit messages and branch names. -To create a merge request description template: +To create a merge request description template for a project: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository**. @@ -87,6 +88,10 @@ For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_templat > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89810) in GitLab 15.7. +NOTE: +This feature is available only for +[the default template](#set-a-default-template-for-merge-requests-and-issues). + When you save a merge request for the first time, GitLab replaces these variables in your merge request template with their values: @@ -95,7 +100,7 @@ your merge request template with their values: | `%{all_commits}` | Messages from all commits in the merge request. Limited to 100 most recent commits. Skips commit bodies exceeding 100 KiB and merge commit messages. | `* Feature introduced` <br><br> `This commit implements feature` <br> `Changelog:added` <br><br> `* Bug fixed` <br><br> `* Documentation improved` <br><br>`This commit introduced better docs.` | | `%{co_authored_by}` | Names and emails of commit authors in a `Co-authored-by` Git commit trailer format. Limited to authors of 100 most recent commits in merge request. | `Co-authored-by: Zane Doe <zdoe@example.com>` <br> `Co-authored-by: Blake Smith <bsmith@example.com>` | | `%{first_commit}` | Full message of the first commit in merge request diff. | `Update README.md` | -| `%{first_multiline_commit}` | Full message of the first commit that's not a merge commit and has more than one line in message body. Merge request title if all commits aren't multiline. | `Update README.md`<br><br>`Improved project description in readme file.` | +| `%{first_multiline_commit}` | Full message of the first commit that's not a merge commit and has more than one line in message body. Merge request title if all commits aren't multiline. | `Update README.md` <br><br> `Improved project description in readme file.` | | `%{source_branch}` | The name of the branch being merged. | `my-feature-branch` | | `%{target_branch}` | The name of the branch that the changes are applied to. | `main` | @@ -148,11 +153,11 @@ To set a default description template for merge requests, either: - [In GitLab 14.8 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78302), [create a merge request template](#create-a-merge-request-template) named `Default.md` (case insensitive) and save it in `.gitlab/merge_request_templates/`. This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings. -- Users on GitLab Premium and higher: set the default template in project settings: +- Users on GitLab Premium and Ultimate: set the default template in project settings: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Merge requests**. - 1. In the **Merge commit message template** section, fill in **Default description template for merge requests**. + 1. In the **Default description template for merge requests** section, fill in the text area. 1. Select **Save changes**. To set a default description template for issues, either: @@ -160,12 +165,12 @@ To set a default description template for issues, either: - [In GitLab 14.8 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78302), [create an issue template](#create-an-issue-template) named `Default.md` (case insensitive) and save it in `.gitlab/issue_templates/`. This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings. -- Users on GitLab Premium and higher: set the default template in project settings: +- Users on GitLab Premium and Ultimate: set the default template in project settings: 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Settings**. - 1. Expand **Default issue template**. - 1. Fill in the **Default description template for issues** text area. + 1. On the left sidebar, select **Settings > General**. + 1. Expand **Default description template for issues**. + 1. Fill in the text area. 1. Select **Save changes**. Because GitLab merge request and issues support [Markdown](../markdown.md), you can use it to format @@ -176,7 +181,7 @@ You can also provide `issues_template` and `merge_requests_template` attributes #### Priority of default description templates -When you set [merge request and issue description templates](#set-a-default-template-for-merge-requests-and-issues) +When you set [issue description templates](#set-a-default-template-for-merge-requests-and-issues) in various places, they have the following priorities in a project. The ones higher up override the ones below: @@ -184,6 +189,9 @@ The ones higher up override the ones below: 1. `Default.md` (case insensitive) from the parent group. 1. `Default.md` (case insensitive) from the project repository. +Merge requests have [additional inheritance rules](merge_requests/creating_merge_requests.md) +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 |