Contribute to built-in project templates

Adding a new built-in project template

If you’d like to contribute a new built-in project template to be distributed with GitLab, please do the following:

  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 here.
    • Projects should be as simple as possible and free of any unnecessary assets or dependencies.
  2. When the project is ready for review, please create a new issue in GitLab with a link to your project.
    • In your issue, @ mention the relevant Backend Engineering Manager and Product Manager for the Create:Source Code group.

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

  1. Create a working template (example)
    • 2 types of built-in templates are available within GitLab:
      • Normal templates: Available in GitLab Core, Starter and above (this is the most common type of built-in template).
        • To contribute a normal template:
          • Add details of the template in the localized_templates_table method in gitlab/lib/gitlab/project_template.rb,
          • Add details of the template in spec/lib/gitlab/project_template_spec.rb, in the test for the all method, and
          • Add details of the template in gitlab/app/assets/javascripts/projects/default_project_templates.js.
          • See MR !25318 for an example
      • Enterprise templates: Introduced in GitLab 12.10, that are available only in GitLab Gold & Ultimate.
        • To contribute an Enterprise template:
          • Add details of the template in the localized_ee_templates_table method in gitlab/ee/lib/ee/gitlab/project_template.rb,
          • Add details of the template in gitlab/ee/spec/lib/gitlab/project_template_spec.rb, in the enterprise_templates method, and
          • Add details of the template in gitlab/ee/app/assets/javascripts/projects/default_project_templates.js.
          • See MR !28187 for an example.

  2. Run the following in the gitlab project, where $name is the name you gave the template in gitlab/project_template.rb:

    bin/rake gitlab:update_project_templates[$name]
  3. Run the bundle_repo script. Make sure to pass the correct arguments, or the script may damage the folder structure.
  4. Add exported project ($name.tar.gz) to gitlab/vendor/project_templates and remove the resulting build folders tar-base and project.
  5. Run bin/rake gettext:regenerate in the gitlab project and commit new .pot file.
  6. Add a changelog entry in the commit message (for example, Changelog: added). For more information, see Changelog entries.
  7. Add an icon to gitlab-svgs, as shown in this example. If a logo is not available for the project, use the default ‘Tanuki’ logo instead.
  8. Run yarn run svgs on gitlab-svgs project and commit result.
  9. Forward changes in gitlab-svgs project to master. This involves:
    • Merging your MR in gitlab-svgs
    • The bot will pick the new release up and create an MR in gitlab-org/gitlab.
  10. Once the bot-created MR created above is merged, you can rebase your template MR onto the updated master to pick up the new svgs.
  11. Test everything is working.

Contributing an improvement to an existing template

Existing templates are available in the project-templates group.

To contribute a change, please 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 on gitlab to ask for it to get updated, or open a merge request updating the vendored template using these instructions.

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>\]

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.