Contribute to built-in project templates

GitLab provides some built-in project templates that you can use when creating a new project.

Built-in templates are sourced from the following groups:

Prerequisites:

You must have a working GitLab Development Kit (GDK) environment. In particular, PostgreSQL, Praefect, and sshd must be working.
wget should be installed.

Add a new built-in project template

If you'd like to contribute a new built-in project template to be distributed with GitLab, there are a few steps to follow.

Create the project

Create a new public project with the project content you'd like to contribute in a namespace of your choosing. You can view a working example.
- Projects should be free of any unnecessary assets or dependencies.
When the project is ready for review, create a new issue with a link to your project.
- In your issue, @ mention the relevant Backend Engineering Manager and Product Manager for the Create:Source Code group.

Add the logo in `gitlab-svgs`

All templates fetch their icons from the gitlab-svgs library, so if the icon of the template you add is not present, you have to submit one.

See how to add a third-party logo.

After the logo is added to the main branch, the bot picks the new release up and create an MR in gitlab-org/gitlab. You can now proceed to the next step.

Add the template details

Two types of built-in templates are available in GitLab:

Standard templates: Available in all GitLab tiers.
Enterprise templates: Available only in GitLab Premium and Ultimate.

To make the project template available when creating a new project, you must follow the vendoring process to create a working template.

Standard template

NOTE: See merge request 25318 for an example.

To contribute a standard template:

Add the details of the template in the localized_templates_table method in lib/gitlab/project_template.rb using the following scheme:

ProjectTemplate.new('<template_name>', '<template_short_description>', _('<template_long_description>'), '<template_project_link>', 'illustrations/logos/<template_logo_name>.svg'),

Add the details of the template in app/assets/javascripts/projects/default_project_templates.js.
Add the template name to spec/support/helpers/project_template_test_helper.rb.

Enterprise template

NOTE: See merge request 28187 for an example.

To contribute an Enterprise template:

Add details of the template in the localized_ee_templates_table method in ee/lib/ee/gitlab/project_template.rb using the following scheme:

ProjectTemplate.new('<template_name>', '<template_short_description>', _('<template_long_description>'), '<template_project_link>', 'illustrations/logos/<template_logo_name>.svg'),

Add the template name in the list of let(:enterprise_templates) in ee/spec/lib/gitlab/project_template_spec.rb.
Add details of the template in ee/app/assets/javascripts/projects/default_project_templates.js.

Populate the template details

Start GDK:
```
gdk start
```
Run the following in the gitlab project, where <template_name> is the name you gave the template in gitlab/project_template.rb:
```
bin/rake "gitlab:update_project_templates[<template_name>]"
```
Regenerate the localization file in the gitlab project and commit the new .pot file:
```
bin/rake gettext:regenerate
```
Add a changelog entry in the commit message (for example, Changelog: added). For more information, see Changelog entries.

Update an existing built-in project template

To contribute a change:

Open a merge request in the relevant project, and leave the following comment when you are ready for a review:

@gitlab-org/manage/import/backend this is a contribution to update the project
template and is ready for review!

@gitlab-bot ready

If your merge request gets accepted:
- Either open an issue to ask for it to get updated.
- Or update the vendored template and open a merge request:
```
bin/rake "gitlab:update_project_templates[<template_name>]"
```

Test your built-in project with the GitLab Development Kit

Complete the following steps to test the project template in your own GDK instance:

Start GDK:
```
gdk start
```
Run the following Rake task, where <template_name> is the name of the template in lib/gitlab/project_template.rb:
```
bin/rake "gitlab:update_project_templates[<template_name>]"
```
Visit GitLab in your browser and create a new project by selecting the project template.

For GitLab team members

Ensure all merge requests have been reviewed by the Security counterpart before merging.

Update all templates

Starting a project from a template needs this project to be exported. On a up to date default branch run:

gdk start # postgres, praefect, and sshd are required
bin/rake gitlab:update_project_templates
git checkout -b update-project-templates
git add vendor/project_templates
git commit
git push -u origin update-project-templates

Now create a merge request and assign to a Security counterpart to merge.

Update a single template

To update just a single template instead of all of them, specify the template name between square brackets. For example, for the jekyll template, run:

bin/rake "gitlab:update_project_templates[jekyll]"

Review a template merge request

To review a merge request which changes one or more vendored project templates, run the check-template-changes script:

scripts/check-template-changes vendor/project_templates/<template_name>.tar.gz

This script outputs a diff of the file changes against the default branch and also verifies that the template repository matches the source template project.