ContextQMD
Back to Gitlabhq

Project templates for your instance

doc/administration/project_templates.md

19.1.05.2 KB
Original Source

{{< details >}}

  • Tier: Premium, Ultimate
  • Offering: GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Project templates populate new projects with files and configuration. On your instance, you can configure custom project templates from a group you manage, and control whether built-in project templates are available to users.

Custom project templates

To speed up the creation of projects on your instance, configure a group that contains template projects. Users can then create new projects based on your templates that include the common tooling and configuration you specify.

To learn more about what data is copied from template projects, see what is copied from the templates.

Before you make template projects available to your instance, select a group to manage the templates. To prevent any unexpected changes to templates, create a new group for this purpose, rather than reusing an existing group. If you reuse an existing group created for a different purpose, users with the Maintainer role might edit the template projects without understanding the side effects.

Select a group to manage template projects

Prerequisites:

  • Administrator access.

To select the group to manage the project templates for your instance:

  1. In the upper-right corner, select Admin.
  2. In the left sidebar, select Settings > Templates.
  3. Expand Custom project templates.
  4. Select a group to use.
  5. Select Save changes.

After you configure the group as a source for project templates, new projects added to this group become available as templates.

Configure a project for use as a template

After you create a group to manage the template projects, configure the visibility and feature availability of each template project.

Prerequisites:

  • You must be either the administrator of the instance, or a user with a role that allows you to configure the project.
  1. Ensure the project belongs to the group directly, and not through a subgroup. Projects from subgroups of the chosen group can't be used as templates.
  2. To configure which users can select the project template, set the project's visibility:
    • Public and Internal projects can be selected by any authenticated user.
    • Private projects can be selected only by members of that project.
  3. Review the project's feature settings. All enabled project features should be set to Everyone With Access, except GitLab Pages and Security and compliance.

Repository and database information that are copied over to each new project are identical to the data exported with GitLab project import and export. This includes the full Git commit history from the template project. For more information, see migrate GitLab data by using file exports.

To create a template without commit history, initialize your template project with a single commit that contains all the files you want to include.

Built-in project templates

{{< history >}}

  • Introduced in GitLab 19.0 with a flag named use_built_in_project_templates_enabled. Disabled by default.

{{< /history >}}

[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.

Built-in project templates populate new projects with starter files. By default, these templates are available to all users. As an administrator, you can turn off this setting for the instance, and optionally enforce it so group Owners cannot override it. Group Owners can also control this setting for their groups.

The setting uses cascading inheritance:

  • By default, root groups inherit the instance value.
  • Subgroups inherit the value from their closest ancestor group.
  • A group-specific value overrides the inherited value.
  • When you enforce the setting for the instance, all groups inherit it.
  • When you enforce the setting for a group, all subgroups inherit it.
  • When you change the instance setting, the new value cascades to all groups.
  • When you change a group setting, the new value cascades to all subgroups.

Configure built-in project templates

Prerequisites:

  • You must be an administrator.

To control built-in project templates for the instance:

  1. In the upper-right corner, select Admin.
  2. Select Settings > Templates.
  3. Expand Built-in project templates.
  4. Select or clear the Enable built-in project templates checkbox.
  5. Optional. To prevent groups from changing this setting, select the Enforce for all groups checkbox.
  6. Select Save changes.