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.
- In your issue,
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
See merge request 25318 for an example.
To contribute a standard template:
Add the details of the template in the
localized_templates_table
method inlib/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
See merge request 28187 for an example.
To contribute an Enterprise template:
Add details of the template in the
localized_ee_templates_table
method inee/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)
inee/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 ingitlab/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 inlib/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.
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support