Contribute to built-in project templates

Adding a new built-in project template

This page provides instructions about how to contribute a built-in project template.

To contribute a built-in project template, you must complete the following tasks:

  1. Create a project template for GitLab review
  2. Add the template SVG icon to GitLab SVGs
  3. Create a merge request with vendor details

You can contribute the following types of project templates:

  • Enterprise: For users with GitLab Premium and above.
  • Non-enterprise: For users with GitLab Free and above.

Prerequisites

To add or update an existing template, you must have the following tools installed:

  • wget
  • tar

Create a project template for review

  1. In your selected namespace, create a public project.
  2. Add the project content you want to use in the template. Do not include unnecessary assets or dependencies. For an example, see this project.
  3. When the project is ready for review, create an issue with a link to your project. In your issue, mention the Create:Source Code Backend Engineering Manager and Product Manager for the Templates feature.

Add the template SVG icon to GitLab SVGs

If the project template has an SVG icon, you must add it to the GitLab SVGs project before you can create a merge request with vendor details.

Create a merge request with vendor details

Before GitLab can implement the project template, you must create a merge request in gitlab-org/gitlab that includes vendor details about the project.

  1. Export the project and save the file as <name>.tar.gz, where <name> is the short name of the project. Move this file to the root directory of gitlab-org/gitlab.
  2. In gitlab-org/gitlab, create and check out a new branch.
  3. Edit the following files to include the project template:
    • For non-Enterprise project templates:

      • In lib/gitlab/project_template.rb, add details about the template in the localized_templates_table method. In the following example, the short name of the project is hugo: 

         ProjectTemplate.new('hugo', 'Pages/Hugo', _('Everything you need to create a GitLab Pages site using Hugo'), 'https://gitlab.com/pages/hugo', 'illustrations/logos/hugo.svg'),

        If the project doesn’t have an SVG icon, exclude , 'illustrations/logos/hugo.svg'.

      • In spec/support/helpers/project_template_test_helper.rb, append the short name of the template in the all_templates method.

      • In app/assets/javascripts/projects/default_project_templates.js, add details of the template. For example: 

         hugo: {
   text: s__('ProjectTemplates|Pages/Hugo'),
   icon: '.template-option .icon-hugo',
 },

        If the project doesn’t have an SVG icon, use .icon-gitlab_logo instead.

    • For Enterprise project templates:

      • In ee/lib/ee/gitlab/project_template.rb, in the localized_ee_templates_table method, add details about the template. For example: 

         ::Gitlab::ProjectTemplate.new('hipaa_audit_protocol', 'HIPAA Audit Protocol', _('A project containing issues for each audit inquiry in the HIPAA Audit Protocol published by the U.S. Department of Health & Human Services'), 'https://gitlab.com/gitlab-org/project-templates/hipaa-audit-protocol', 'illustrations/logos/asklepian.svg')
      • In ee/spec/lib/gitlab/project_template_spec.rb, add the short name of the template in the .all test.

      • In ee/app/assets/javascripts/projects/default_project_templates.js, add the template details. For example: 

         hipaa_audit_protocol: {
   text: s__('ProjectTemplates|HIPAA Audit Protocol'),
   icon: '.template-option .icon-hipaa_audit_protocol',
 },

  4. Run the following Rake task, where <path>/<name> is the name you gave the template in lib/gitlab/project_template.rb: 

    bin/rake gitlab:update_project_templates\[<path>/<name>\]

  5. Regenerate gitlab.pot: 

    bin/rake gettext:regenerate
  6. After you run the scripts, there is one new file in vendor/project_templates/ and four changed files. Commit all changes and push your branch to update the merge request. For an example, see this merge request.

Test your built-in project with the GitLab Development Kit

Complete the following steps to test the project template in your own GitLab Development Kit instance:

  1. Run the following Rake task, where <path>/<name> is the name you gave the template in lib/gitlab/project_template.rb: 

    bin/rake gitlab:update_project_templates\[<path>/<name>\]

Contribute an improvement to an existing template

To update an existing built-in project template, changes are usually made to the existing template, found in the project-templates group. A merge request is made directly against the template and the Create:Source Code Backend Engineering Manager and Product Manager pinged for review.

Sometimes it is necessary to completely replace the template files. In this case the process would be:

  1. Create a merge request in the relevant project of the project-templates and pages group and mention @gitlab-org/manage/import/backend when you are ready for a review.
  2. If your merge request is accepted, either:

For GitLab team members

Please ensure the merge request has been reviewed by the Security Counterpart before merging.

To review a merge request which changes a vendored project template, 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.