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:
- 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.
- 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.
- In your issue,
To make the project template available when creating a new project, the vendoring process will have to be completed:
- Create a working template (example)
- 2 types of built-in templates are available within GitLab:
-
Standard templates: Available in GitLab Core, Starter and above (this is the most common type of built-in template).
- To contribute a standard template:
- Add details of the template in the
localized_templates_table
method ingitlab/lib/gitlab/project_template.rb
, - Add details of the template in
spec/lib/gitlab/project_template_spec.rb
, in the test for theall
method, and - Add details of the template in
gitlab/app/assets/javascripts/projects/default_project_templates.js
. - See MR !25318 for an example
- Add details of the template in the
- To contribute a standard template:
-
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 ingitlab/ee/lib/ee/gitlab/project_template.rb
, - Add details of the template in
gitlab/ee/spec/lib/gitlab/project_template_spec.rb
, in theenterprise_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.
- Add details of the template in the
- To contribute an Enterprise template:
-
Standard templates: Available in GitLab Core, Starter and above (this is the most common type of built-in template).
- 2 types of built-in templates are available within GitLab:
-
Run the following in the
gitlab
project, where$name
is the name you gave the template ingitlab/project_template.rb
:bin/rake gitlab:update_project_templates[$name]
- Run the
bundle_repo
script. Make sure to pass the correct arguments, or the script may damage the folder structure. - Add exported project (
$name.tar.gz
) togitlab/vendor/project_templates
and remove the resulting build folderstar-base
andproject
. - Run
bin/rake gettext:regenerate
in thegitlab
project and commit new.pot
file. - Add a changelog entry in the commit message (for example,
Changelog: added
). For more information, see Changelog entries. - 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. - Run
yarn run svgs
ongitlab-svgs
project and commit result. - Forward changes in
gitlab-svgs
project to themain
branch. This involves:- Merging your MR in
gitlab-svgs
-
The bot
will pick the new release up and create an MR in
gitlab-org/gitlab
.
- Merging your MR in
- After the bot-created MR created above is merged, you can rebase your template MR onto the updated
master
to pick up the new SVGs. - 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:
-
Run the following Rake task, where
<path>/<name>
is the name you gave the template inlib/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.