1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
---
stage: Manage
group: Workspace
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments"
---
# Contribute to GitLab project templates
Thanks for considering a contribution to the GitLab
[built-in project templates](../user/project/working_with_projects.md#create-a-project-from-a-built-in-template).
## 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](https://gitlab.com/gitlab-org/project-templates/dotnetcore).
Projects should be as simple as possible and free of any unnecessary assets or dependencies.
1. When the project is ready for review, [create a new issue](https://gitlab.com/gitlab-org/gitlab/issues) with a link to your project.
In your issue, `@` mention the relevant Backend Engineering Manager and Product
Manager for the [Templates feature](https://about.gitlab.com/handbook/product/categories/#source-code-group).
## 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](https://gitlab.com/gitlab-org/gitlab-svgs/-/blob/main/README.md#adding-icons-or-illustrations)
and submit a merge request.
1. When the merge request is merged, `gitlab-bot` will pull the new changes in
the `gitlab-org/gitlab` project.
1. 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](../user/project/settings/import_export.md#export-a-project-and-its-data)
you created in the previous step and save the file as `<name>.tar.gz`, where
`<name>` is the short name of the project.
1. 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](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/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`:
```ruby
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'`.
1. Open `spec/lib/gitlab/project_template_spec.rb` and add the short name
of the template in the `.all` test.
1. Open `app/assets/javascripts/projects/default_project_templates.js` and
add details of the template. For example:
```javascript
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](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/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:
```ruby
::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')
```
1. Open `ee/spec/lib/gitlab/project_template_spec.rb` and add the short name
of the template in the `.all` test.
1. Open `ee/app/assets/javascripts/projects/default_project_templates.js` and
add details of the template. For example:
```javascript
hipaa_audit_protocol: {
text: s__('ProjectTemplates|HIPAA Audit Protocol'),
icon: '.template-option .icon-hipaa_audit_protocol',
},
```
1. Run the `vendor_template` script. Make sure to pass the correct arguments:
```shell
scripts/vendor_template <git_repo_url> <name> <comment>
```
1. Regenerate `gitlab.pot`:
```shell
bin/rake gettext:regenerate
```
1. 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:
```yaml
# gitlab-development-kit/gdk.yml
praefect:
enabled: false
```
1. Follow the steps described in the [vendoring process](#vendoring-process).
1. Run the following Rake task where `<path>/<name>` is the
name you gave the template in `lib/gitlab/project_template.rb`:
```shell
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:
- [`project-templates`](https://gitlab.com/gitlab-org/project-templates)
- [`pages`](htps://gitlab.com/pages)
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](https://gitlab.com/gitlab-org/gitlab/-/issues)
to ask for it to get updated, or open a merge request updating
the [vendored template](#vendoring-process).
|
