描述模板
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
描述模板标准化并自动化了在 GitLab 中创建问题和合并请求的方式。
描述模板：
- 在项目间为问题和合并请求创建一致的布局。
- 为不同的工作流程阶段和用途提供专用模板。
- 支持项目、群组和整个实例的自定义模板。
- 使用变量和快速操作自动填充字段。
- 确保对错误、功能和其他工作项的正确跟踪。
- 格式化服务台邮件回复。
您可以定义模板用作以下内容的描述：
项目从其群组和实例继承模板。
模板必须：
- 以
.md扩展名保存。 - 存储在项目仓库的
.gitlab/issue_templates或.gitlab/merge_request_templates目录中。 - 存在于默认分支上。
创建描述模板
在仓库的 .gitlab/issue_templates/ 目录中创建一个新的 Markdown (.md) 文件作为描述模板。
要创建工作项描述模板：
- 在左侧边栏，选择 搜索或跳转 并找到您的项目。
- 选择 代码 > 仓库。
- 在默认分支旁边，选择 。
- 选择 新建文件。
- 在默认分支旁边，在 文件名 文本框中，输入
.gitlab/issue_templates/mytemplate.md， 其中mytemplate是您的模板名称。 - 提交到您的默认分支。
要检查是否正确工作：
创建合并请求模板
与问题模板类似，在仓库的 .gitlab/merge_request_templates/ 目录中创建一个新的 Markdown (.md) 文件。与问题模板不同，合并请求有额外的继承规则，这些规则依赖于提交消息和分支名称的内容。
要为项目创建合并请求描述模板：
- 在左侧边栏，选择 搜索或跳转 并找到您的项目。
- 选择 代码 > 仓库。
- 在默认分支旁边，选择 。
- 选择 新建文件。
- 在默认分支旁边，在 文件名 文本框中，输入
.gitlab/merge_request_templates/mytemplate.md， 其中mytemplate是您的合并请求模板名称。 - 提交到您的默认分支。
要检查是否正确工作，创建新的合并请求， 并查看 选择模板 下拉列表中是否能找到您的描述模板。
使用模板
当您创建或编辑问题或合并请求时，它会显示在 选择模板 下拉列表中。
要应用模板：
- 创建或编辑问题、工作项或合并请求。
- 选择 选择模板 下拉列表。
- 如果 描述 文本框不为空，请确认，然后选择 应用模板。
- 选择 保存更改。
当您选择描述模板时，其内容会被复制到描述文本框中。
要放弃选择模板后对描述所做的任何更改：展开 选择模板 下拉列表并选择 重置模板。
您可以创建快捷链接来使用指定模板创建问题。
例如：https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal。了解更多关于使用预填充值的 URL 创建问题的信息。
合并请求模板中支持的变量
此功能仅适用于默认模板。
当您第一次保存合并请求时，GitLab 会用这些值替换合并请求模板中的这些变量：
| 变量 | 描述 | 输出示例 |
|---|---|---|
%{all_commits} |
合并请求中所有提交的消息。限制为最近 100 个提交。跳过超过 100 KiB 的提交正文和合并提交消息。 | * 功能引入 此提交实现了功能 变更日志：已添加 * 错误修复 * 文档改进 此提交引入了更好的文档。 |
%{co_authored_by} |
提交作者在 Co-authored-by Git 提交尾行格式中的姓名和邮箱。限制为合并请求中最近 100 个提交的作者。 |
Co-authored-by: Zane Doe <zdoe@example.com> Co-authored-by: Blake Smith <bsmith@example.com> |
%{first_commit} |
合并请求差异中第一个提交的完整消息。 | 更新 README.md |
%{first_multiline_commit} |
第一个非合并提交且消息正文有多行的完整消息。如果所有提交都不是多行，则为合并请求标题。 | 更新 README.md 改进了 readme 文件中的项目描述。 |
%{first_multiline_commit_description} |
第一个非合并提交且消息正文有多行的描述（不包括第一行/标题）。 | 改进了 readme 文件中的项目描述。 |
%{source_branch} |
正在合并的分支名称。 | my-feature-branch |
%{target_branch} |
应用更改的分支名称。 | main |
设置实例级描述模板
- Tier: Premium, Ultimate
- Offering: GitLab Self-Managed, GitLab Dedicated
您可以使用实例模板仓库为问题和合并请求设置实例级描述模板。 您也可以使用实例模板仓库作为文件模板。
您可能还对项目模板感兴趣，这些模板可用于在实例中创建新项目。
设置群组级描述模板
- Tier: Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
使用群组级描述模板，您可以选择群组内的一个项目来存储您的模板。然后，您可以在群组中的其他项目中访问这些模板。 因此，您可以在群组所有项目的问题和合并请求中使用相同的模板。
先决条件：
- 您必须拥有群组的所有者角色。
- 项目必须是群组的直接子项目。
要重用您已创建的模板：
- 在左侧边栏，选择 搜索或跳转 并找到您的群组。
- 选择 设置 > 常规。
- 展开 模板。
- 从下拉列表中，选择您的模板项目作为群组级的模板仓库。
- 选择 保存更改。
您可能还对各种群组中的文件类型模板感兴趣。
为合并请求和问题设置默认模板
在项目中，您可以为新问题和合并请求选择默认描述模板。 因此，每次创建新的合并请求或问题时，都会用您在模板中输入的文本预填充。
先决条件：
- 在项目左侧边栏，选择 设置 > 常规 并展开 可见性、项目功能、权限。 确保问题或合并请求设置为 所有有权限的用户 或 仅项目成员。
要为合并请求设置默认描述模板，可以选择：
-
创建合并请求模板 并命名为
Default.md（不区分大小写） 并将其保存在.gitlab/merge_request_templates/中。 如果已在项目设置中设置了默认模板，这不会覆盖它。 -
GitLab Premium 和 Ultimate 用户：在项目设置中设置默认模板：
- 在左侧边栏，选择 搜索或跳转 并找到您的项目。
- 选择 设置 > 合并请求。
- 在 合并请求的默认描述模板 部分，填写文本区域。
- 选择 保存更改。
要为问题设置默认描述模板，可以选择：
-
创建问题模板 并命名为
Default.md（不区分大小写） 并将其保存在.gitlab/issue_templates/中。 如果已在项目设置中设置了默认模板，这不会覆盖它。 -
GitLab Premium 和 Ultimate 用户：在项目设置中设置默认模板：
- 在左侧边栏，选择 搜索或跳转 并找到您的项目。
- 选择 设置 > 常规。
- 展开 问题的默认描述模板。
- 填写文本区域。
- 选择 保存更改。
由于 GitLab 合并请求和问题支持 Markdown，您可以使用它来格式化 标题、列表等。
您还可以在项目 REST API中提供 issues_template 和 merge_requests_template 属性，
以保持您默认的问题和合并请求模板为最新。
默认描述模板的优先级
当您在不同位置设置问题描述模板时， 它们在项目中有以下优先级。较高的会覆盖较低的：
- 在项目设置中设置的模板。
- 来自父群组的
Default.md（不区分大小写）。 - 来自项目仓库的
Default.md（不区分大小写）。
合并请求有额外的继承规则，这些规则依赖于提交消息和分支名称的内容。
示例描述模板
我们使用 GitLab 项目 .gitlab 文件夹中的问题和合并请求描述模板，您可以参考这些模板获取一些示例。
可以在描述模板中使用快速操作来快速添加标签、指派人和里程碑。只有提交问题或合并请求的用户具有执行相关操作的权限时，才会执行快速操作。
以下是一个错误报告模板的示例：
## 概要
<!-- HTML 注释不会显示 -->
（简洁地总结遇到的错误）
## 复现步骤
（如何复现此问题 - 这非常重要）
## 示例项目
（如果可能，在 GitLab.com 上创建一个展示问题行为的示例项目，并在错误报告中链接到此。
如果您使用的是旧版本的 GitLab，这也将确定该错误是否已在更新的版本中修复）
## 当前错误行为是什么？
（实际发生的情况）
## 期望的正确行为是什么？
（您应该看到的情况）
## 相关日志和/或截图
（粘贴任何相关日志 - 使用代码块（```）来格式化控制台输出、日志和代码，否则很难阅读。）
## 可能的修复
（如果可以，链接到可能负责问题的代码行）
/label ~bug ~reproduced ~needs-investigation
/cc @project-manager
/assign @qa-tester