diff options
Diffstat (limited to 'doc/user/project/description_templates.md')
| -rw-r--r-- | doc/user/project/description_templates.md | 112 |
1 files changed, 92 insertions, 20 deletions
diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index c56470ee07a..2267cb55f16 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -20,7 +20,7 @@ Every GitLab project can define its own set of description templates as they are added to the root directory of a GitLab project's repository. Description templates must be written in [Markdown](../markdown.md) and stored -in your project's repository under a directory named `.gitlab`. Only the +in your project's repository in the `.gitlab` directory. Only the templates of the default branch are taken into account. To learn how to create templates for various file types in groups, visit @@ -28,19 +28,23 @@ To learn how to create templates for various file types in groups, visit ## Use cases +These are some situations when you might find description templates useful: + +- You can create issues and merge request templates for different + stages of your workflow, for example, feature proposal, feature improvement, or a bug report. - Add a template to be used in every issue for a specific project, giving instructions and guidelines, requiring for information specific to that subject. For example, if you have a project for tracking new blog posts, you can require the - title, outlines, author name, author social media information, and so on. + title, outlines, author name, and author social media information. - Following the previous example, you can make a template for every MR submitted with a new blog post, requiring information about the post date, front matter data, images guidelines, link to the related issue, reviewer name, and so on. - You can also create issues and merge request templates for different stages of your workflow, for example, feature proposal, feature improvement, or a bug report. -- You can use an [issue description template](#creating-issue-templates) as a +- You can use an [issue description template](#create-an-issue-template) as a [Service Desk email template](service_desk.md#new-service-desk-issues). -## Creating issue templates +## Create an issue template Create a new Markdown (`.md`) file inside the `.gitlab/issue_templates/` directory in your repository. Commit and push to your default branch. @@ -65,13 +69,13 @@ To create the `.gitlab/issue_templates` directory: To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-a-new-issue) and see if you can choose a description template. -## Creating merge request templates +## 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. -## Using the templates +## Use the templates Let's take for example that you've created the file `.gitlab/issue_templates/Bug.md`. This enables the `Bug` dropdown option when creating or editing issues. When @@ -85,42 +89,85 @@ For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_templat  -## Setting a default template for merge requests and issues **(PREMIUM)** +### Set an issue and merge request description template at group level **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. +> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - It's disabled by default on GitLab.com. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to + [enable it](#enable-or-disable-issue-and-merge-request-description-templates-at-group-and-instance-level). + +Templates can be useful because you can create a template once and use it multiple times. +To re-use templates [you've created](../project/description_templates.md#create-an-issue-template): + +1. Go to the group's **Settings > General > Templates**. +1. From the dropdown, select your template project as the template repository at group level. + + + +### Set an issue and merge request description template at instance level **(PREMIUM ONLY)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. +> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - It's disabled by default on GitLab.com. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to + [enable it](#enable-or-disable-issue-and-merge-request-description-templates-at-group-and-instance-level). + +Similar to group templates, issue and merge request templates can also be set up at the instance level. +This results in those templates being available in all projects within the instance. +Only instance administrators can set instance-level templates. + +To set the instance-level description template repository: + +1. Select the **Admin Area** icon (**{admin}**). +1. Go to **Settings > Templates**. +1. From the dropdown, select your template project as the template repository at instance level. + +Learn more about [instance template repository](../admin_area/settings/instance_template_repository.md). + + -> - Moved to GitLab Premium in 13.9. +### Set a default template for merge requests and issues **(PREMIUM)** The visibility of issues or merge requests should be set to either "Everyone with access" or "Only Project Members" in your project's **Settings / Visibility, project features, permissions** section, otherwise the template text areas don't show. This is the default behavior, so in most cases you should be fine. +To set a default description template for merge requests: + 1. Go to your project's **Settings**. -1. Click **Expand** under the **Merge requests** header. +1. Select **Expand** under the **Merge requests** header. 1. Fill in the **Default description template for merge requests** text area. -1. Click **Expand** under **Default issue template**. +1. Select **Save changes**. + +To set a default description template for issues: + +1. Select **Expand** under **Default issue template**. 1. Fill in the **Default description template for issues** text area. - Since GitLab merge request and issues support [Markdown](../markdown.md), you can use it to format - headings, lists, and so on. - +Because GitLab merge request and issues support [Markdown](../markdown.md), you can use it to format +headings, lists, and so on. - +Now, every time a new merge request or issue is created, it's pre-filled with the text you entered +in the templates. -After you add the description, hit **Save changes** for the settings to take -effect. Now, every time a new merge request or issue is created, it is -pre-filled with the text you entered in the template(s). +[GitLab versions 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/885) +provide `issues_template` and `merge_requests_template` attributes in the +[Projects API](../../api/projects.md) to help you keep your templates up to date. ## Description template example -We make use of description templates for issues and merge requests in the GitLab project. -For some examples, refer to the [`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab). +We use description templates for issues and merge requests in the +[`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab) of the +GitLab project, which you can refer to for some examples. NOTE: It's possible to use [quick actions](quick_actions.md) in description templates to quickly add labels, assignees, and milestones. The quick actions are only executed if the user submitting the issue or merge request has the permissions to perform the relevant actions. -Here is an example of a Bug report template: +Here is an example of a bug report template: ```markdown ## Summary @@ -159,3 +206,28 @@ it's very hard to read otherwise.) /cc @project-manager /assign @qa-tester ``` + +## Enable or disable issue and merge request description templates at group and instance level + +Setting issue and merge request description templates at group and instance levels +is under development and not ready for production use. It is deployed behind a +feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:inherited_issuable_templates) +``` + +To disable it: + +```ruby +Feature.disable(:inherited_issuable_templates) +``` + +The feature flag affects these features: + +- Setting a templates project as issue and merge request description templates source at group level. +- Setting a templates project as issue and merge request description templates source at instance level. |