diff options
Diffstat (limited to 'doc/user/project/description_templates.md')
| -rw-r--r-- | doc/user/project/description_templates.md | 83 |
1 files changed, 53 insertions, 30 deletions
diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 2267cb55f16..3acef242cef 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -51,8 +51,10 @@ directory in your repository. Commit and push to your default branch. To create a Markdown file: -1. Click the `+` button next to `master` and click **New file**. -1. Add the name of your issue template to the **File name** text field next to `master`. +1. In a project, go to **Repository**. +1. Next to the default branch, select the **{plus}** button. +1. Select **New file**. +1. Next to the default branch, in the **File name** field, add the name of your issue template. Make sure that your file has the `.md` extension, for example `feature_request.md` or `Feature Request.md`. 1. Commit and push to your default branch. @@ -61,9 +63,12 @@ If you don't have a `.gitlab/issue_templates` directory in your repository, you To create the `.gitlab/issue_templates` directory: -1. Click the `+` button next to `master` and select **New directory**. +1. In a project, go to **Repository**. +1. Next to the default branch, select the **{plus}** button. +1. Select **New directory**. 1. Name this new directory `.gitlab` and commit to your default branch. -1. Click the `+` button next to `master` again and select **New directory**. +1. Next to the default branch, select the **{plus}** button. +1. Select **New directory**. 1. Name your directory `issue_templates` and commit to your default branch. To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-a-new-issue) @@ -89,32 +94,27 @@ For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_templat  -### Set an issue and merge request description template at group level **(PREMIUM)** +You can set description templates at various levels: -> - [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. +- The entire [instance](#set-instance-level-description-templates) +- A specific [group or subgroup](#set-group-level-description-templates) +- A specific [project](#set-a-default-template-for-merge-requests-and-issues) - +The templates are inherited. For example, in a project, you can also access templates set for the +instance or the project's parent groups. -### Set an issue and merge request description template at instance level **(PREMIUM ONLY)** +### Set instance-level description templates **(PREMIUM SELF)** > - [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). +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56737) in GitLab 13.11. +> - It's enabled by default on GitLab.com. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-issue-and-merge-request-description-templates-at-group-and-instance-level). **(PREMIUM SELF)** + +You can set a description template at the **instance level** for issues +and merge requests. +As a result, these templates are available in all projects within the instance. -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: @@ -122,15 +122,41 @@ 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. +1. Select **Save changes**. + + Learn more about [instance template repository](../admin_area/settings/instance_template_repository.md). - +### Set group-level description templates **(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. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56737) in GitLab 13.11. +> - It's enabled by default on GitLab.com. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-issue-and-merge-request-description-templates-at-group-and-instance-level). **(PREMIUM SELF)** + +With **group-level** description templates, you can store your templates in a single repository and +configure the group file templates setting to point to that repository. +As a result, you can use the same templates in issues and merge requests in all the group's projects. + +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. +1. Select **Save changes**. + + ### Set a default template for merge requests and issues **(PREMIUM)** +In a project, you can choose a default description template for new issues and merge requests. +As a result, every time a new merge request or issue is created, it's pre-filled with the text you +entered in the template. + 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 +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. @@ -149,9 +175,6 @@ To set a default description template for issues: 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. - [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. @@ -211,9 +234,9 @@ it's very hard to read otherwise.) 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**. +feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. +can disable it. To enable it: |