Contribute to GitLab project templates

Thanks for considering a contribution to the GitLab built-in project templates.

Prerequisites

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

  • wget
  • tar
  • jq

Create a new project

To contribute a new built-in project template to be distributed with GitLab:

  1. 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 as simple as possible and free of any unnecessary assets or dependencies.
  2. 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 Templates feature.

Add the SVG icon to GitLab SVGs

If the template you’re adding has an SVG icon, you need to first add it to https://gitlab.com/gitlab-org/gitlab-svgs:

  1. Follow the steps outlined in the GitLab SVGs project and submit a merge request.
  2. When the merge request is merged, gitlab-bot will pull the new changes in the gitlab-org/gitlab project.
  3. You can now continue on the vendoring process.

Vendoring process

To make the project template available when creating a new project, the vendoring process will have to be completed:

  1. Export the project you created in the previous step and save the file as <name>.tar.gz, where <name> is the short name of the project.
  2. Edit the following files to include the project template. Two types of built-in templates are available within GitLab:

    • Normal templates: Available in GitLab Free and above (this is the most common type of built-in template). See MR !25318 for an example.

      To add a normal template:

      1. Open lib/gitlab/project_template.rb and add details of 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 vendored project doesn’t have an SVG icon, omit , 'illustrations/logos/hugo.svg'.

      2. Open spec/lib/gitlab/project_template_spec.rb and add the short name of the template in the .all test.

      3. Open app/assets/javascripts/projects/default_project_templates.js and add details of the template. For example: 

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

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

    • Enterprise templates: Introduced in GitLab 12.10, that are available only in GitLab Premium and above. See MR !28187 for an example.

      To add an Enterprise template:

      1. Open ee/lib/ee/gitlab/project_template.rb and add details of the template in the localized_ee_templates_table method. 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')
      2. Open ee/spec/lib/gitlab/project_template_spec.rb and add the short name of the template in the .all test.

      3. Open ee/app/assets/javascripts/projects/default_project_templates.js and add details of the template. For example: 

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

  3. Run the vendor_template script. Make sure to pass the correct arguments: 

    scripts/vendor_template <git_repo_url> <name> <comment>

  4. Regenerate gitlab.pot: 

    bin/rake gettext:regenerate
  5. By now, there should be one new file under vendor/project_templates/ and 4 changed files. Commit all of them in a new branch and create a merge request.

Test with GDK

If you are using the GitLab Development Kit (GDK) you must disable praefect and regenerate the Procfile, as the Rake task is not currently compatible with it: 

# gitlab-development-kit/gdk.yml
praefect:
  enabled: false
  1. Follow the steps described in the vendoring process.

  2. 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>]

You can now test to create a new project by importing the new template in GDK.

Contribute an improvement to an existing template

Existing templates are imported from the following groups:

To contribute a change, open a merge request in the relevant project and mention @gitlab-org/manage/import/backend when you are ready for a review.

Then, if your merge request gets accepted, either open an issue to ask for it to get updated, or open a merge request updating the vendored template.