Custom Project Templates
You can use any project in YouTrack as a custom template for new projects. This helps you define one or more basic configurations for projects in addition to the templates that are predefined in YouTrack. When marked as a custom project template, the project is added to the list of available project types on the Create Project page.
warning
Limited Availability for Projects that are Marked as TemplatesProjects that are marked as custom project templates are not accessible in the same way as active projects.
The project is not available in the search context.
It cannot be referenced in search queries or commands.
It is not available in the list for creating new issues.
This behavior is similar to projects that have been archived.
If you have an active project that you would like to use as a custom project template, you can clone it first, then mark the cloned project as a template. This lets you continue to work with and add issues to the active project. To learn how to clone a project, see Clone a Project.
Before you mark a project as a custom project template, review the settings that are described on this page to make sure you understand how the settings for the current project are applied to new projects.
Consider editing the name and description of any project that you want to use as a custom template. These values help other users know which template to choose on the Create Project page.
Make sure the project uses all of the custom fields that you want to use in multiple projects and that these fields store the desired values.
Make sure the workflows that are attached to the project do not depend on the current project to function properly. Detach any workflows that rely on references to a specific project.
To mark a project as a custom project template
tip
Requires permissions: Update Project
Click the Projects link in the header to open the Projects list.
From the Administration menu of the project that you want to use as a project template, select General.
Enable the Custom project template option.
Click the Apply changes button.
The current project is marked as a custom project template.
A template badge is added to the header of the Edit Project page.
The project is added as a Project Type on the Create Project page.
Any project that is created using the custom project template uses the settings that are stored in the source project at the time the new project is created. Modifications to the project that you use as a custom template are not replicated to projects that have already been created from the template. Changes to the configuration of the source project are only applied to projects that are created from the template after the changes are applied.
To create a project from a custom project template, follow the same steps that you would use to create a project from a predefined project template. For instructions, see Create a Project.
Project Settings
The following table describes how each of the settings in the project that is used as a custom template is applied to new projects:
Settings | Description |
|---|---|
General | Most of the general settings from the custom project template are copied to the new project. Values for the following settings are defined when you create the new project:
|
Access | All of the roles that are assigned directly to users and groups in the custom project template are granted to the same set of users and groups in the new project. An exception is made for the Project Admin role, which is assigned to the user who creates the new project. |
Team | All of the users and groups who are members of the team in the custom project template are added to the project team in the new project. The user who creates the project is added to the team as the project owner. |
Fields | All of the custom fields that are available in the custom project template are added to the new project. The sets of values that are available in each of these fields are copied to the new project as well. If the user who creates the project is not included in the set of values for the Assignee field, this user is added to the set in the new project. As with the predefined Scrum and Kanban templates, the settings that auto-attach custom fields to new projects are ignored. |
VCS | All of the VCS integrations that link the project that is used as a custom template to a repository in a version control system are copied to the new project. The VCS integrations are disabled in the new project. |
Notification Templates | Any notification templates that have been customized in the custom project template are copied to the new project. |
Build Server Integration | All of the build server integrations that map the project that is used as a custom template to a build in a version control system are copied to the new project. The mappings are disabled in the new project. This gives you a chance to re-use most of the settings from the original project without adding new mappings. You can edit the mapping to point to a different build on the build server and enable the integration. |
Time Tracking | If time tracking is enabled in the project that is used as a custom template, the feature is enabled in the new project as well. The fields that are set as the Estimate field and Time spent field are set in the new project. All of the work item types that are used in the custom project template are copied to the new project. |
Workflow | Only the workflows that are attached to the project that is used as a custom template are attached to the new project. The global settings that auto-attach workflows to new projects are ignored. |
Agile Boards and Mailbox Integrations
In addition to the project settings, several configurations that are associated with the project that is used as a custom template are included when you use this template to create a new project. This can include configurations for agile boards and mailbox integrations. The following table describes the logic for generating these objects when a custom template is applied to a new project:
Configuration | Description |
|---|---|
Agile Boards | Agile boards are added to the custom project template and automatically generated for new projects when the following conditions are met:
The configuration for the new board is copied from the board that manages issues in the template project, with the following exceptions:
|
Mailbox Integrations | All of the mailbox rules that reference the project that is used as a custom template are copied to the new project. The mailbox rules are disabled in the new project. This gives your administrator a chance to re-use most of the settings from the original rule without adding new mailbox rules. A user who has access to the Mailbox Integrations page can simply edit the mailbox rule to fetch messages from a unique inbox and enable the integration. For more information, see Define Mailbox Rules. |
Hub Projects | If your YouTrack Standalone installation is integrated with an external Hub service, a Hub project is created as a container for the new YouTrack project. The new YouTrack project is added to the Hub project as a resource. All of the settings that are normally inherited from the Hub project, like the project team and access scheme, are copied from the new YouTrack project to the Hub project. |
Items Excluded from the Custom Project Template
The custom template doesn't create copies of all of the objects and integration settings that reference the project that is used as a custom template. The items that are listed in the following table are not copied to new projects:
Item | Description |
|---|---|
Issues | Issues that belong to the project that is used as a custom template are not copied to the new project. |
Reports | Reports that show data for issues in the project that is used as a custom template are not cloned. |
Zendesk Integrations | Settings that let you share Zendesk tickets with issues in YouTrack cannot be copied to the new project. The invitation to share tickets with a third-party system must be initiated in the Zendesk instance. To learn how to set up a Zendesk integration in the new project, see Zendesk Integration. |