Add latest changes from gitlab-org/gitlab@13-2-stable-ee

3 files changed, 72 insertions, 2 deletions

diff --git a/doc/development/cicd/img/ci_template_selection_v13_1.png b/doc/development/cicd/img/ci_template_selection_v13_1.png
new file mode 100644
index 00000000000..af9f6dd1a90
--- /dev/null
+++ b/doc/development/cicd/img/ci_template_selection_v13_1.png
diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md
index 42d4b494544..e0cca00fd69 100644
--- a/doc/development/cicd/index.md
+++ b/doc/development/cicd/index.md
@@ -2,6 +2,8 @@
 
 Development guides that are specific to CI/CD are listed here.
 
+If you are creating new CI/CD templates, please read [the development guide for GitLab CI/CD templates](templates.md).
+
 ## CI Architecture overview
 
 The following is a simplified diagram of the CI architecture. Some details are left out in order to focus on
@@ -90,7 +92,8 @@ A job with the `created` state won't be seen by the Runner yet. To make it possi
 
 When the Runner is connected, it requests the next `pending` job to run by polling the server continuously.
 
-NOTE: **Note:** API endpoints used by the Runner to interact with GitLab are defined in [`lib/api/runner.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/runner.rb)
+NOTE: **Note:**
+API endpoints used by the Runner to interact with GitLab are defined in [`lib/api/runner.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/runner.rb)
 
 After the server receives the request it selects a `pending` job based on the [`Ci::RegisterJobService` algorithm](#ciregisterjobservice), then assigns and sends the job to the Runner.
 
@@ -124,7 +127,8 @@ There are 3 top level queries that this service uses to gather the majority of t
 
 This list of jobs is then filtered further by matching tags between job and Runner tags.
 
-NOTE: **Note:** If a job contains tags, the Runner will not pick the job if it does not match **all** the tags.
+NOTE: **Note:**
+If a job contains tags, the Runner will not pick the job if it does not match **all** the tags.
 The Runner may have more tags than defined for the job, but not vice-versa.
 
 Finally if the Runner can only pick jobs that are tagged, all untagged jobs are filtered out.
diff --git a/doc/development/cicd/templates.md b/doc/development/cicd/templates.md
new file mode 100644
index 00000000000..904e7adffe2
--- /dev/null
+++ b/doc/development/cicd/templates.md
@@ -0,0 +1,66 @@
+# Development guide for GitLab CI/CD templates
+
+This document explains how to develop [GitLab CI/CD templates](../../ci/examples/README.md).
+
+## Place the template file in a relevant directory
+
+All template files reside in the `lib/gitlab/ci/templates` directory, and are categorized by the following sub-directories:
+
+| Sub-directroy | Content                                                      | [Selectable in UI](#make-sure-the-new-template-can-be-selected-in-ui) |
+|---------------|--------------------------------------------------------------|-----------------------------------------------------------------------|
+| `/Jobs/*`     | Auto DevOps related jobs                                     | Yes                                                                   |
+| `/Pages/*`    | Static site generators for GitLab Pages (for example Jekyll) | Yes                                                                   |
+| `/Security/*` | Security related jobs                                        | Yes                                                                   |
+| `/Verify/*`   | Verify/testing related jobs                                  | Yes                                                                   |
+| `/Worklows/*` | Common uses of the `workflow:` keyword                       | No                                                                    |
+| `/*` (root)   | General templates                                            | Yes                                                                   |
+
+## Criteria
+
+The file must follow the [`.gitlab-ci.yml` syntax](../../ci/yaml/README.md).
+Verify it's valid by pasting it into the CI lint tool at `https://gitlab.com/gitlab-org/gitlab/-/ci/lint`.
+
+Also, all templates must be named with the `*.gitlab-ci.yml` suffix.
+
+### Backward compatibility
+
+A template might be dynamically included with the `include:template:` keyword. If
+you make a change to an *existing* template, you must make sure that it won't break
+CI/CD in existing projects.
+
+## Testing
+
+Each CI/CD template must be tested in order to make sure that it's safe to be published.
+
+### Manual QA
+
+It's always good practice to test the template in a minimal demo project.
+To do so, please follow the following steps:
+
+1. Create a public sample project on <https://gitlab.com>.
+1. Add a `.gitlab-ci.yml` to the project with the proposed template.
+1. Run pipelines and make sure that everything runs properly, in all possible cases
+   (merge request pipelines, schedules, and so on).
+1. Link to the project in the description of the merge request that is adding a new template.
+
+This is useful information for reviewers to make sure the template is safe to be merged.
+
+### Make sure the new template can be selected in UI
+
+Templates located under some directories are also [selectable in the **New file** UI](#place-the-template-file-in-a-relevant-directory).
+When you add a template into one of those directories, make sure that it correctly appears in the dropdown:
+
+![CI/CD template selection](img/ci_template_selection_v13_1.png)
+
+### Write an RSpec test
+
+You should write an RSpec test to make sure that pipeline jobs will be generated correctly:
+
+1. Add a test file at `spec/lib/gitlab/ci/templates/<template-category>/<template-name>_spec.rb`
+1. Test that pipeline jobs are properly created via `Ci::CreatePipelineService`.
+
+## Security
+
+A template could contain malicious code. For example, a template that contains the `export` shell command in a job
+might accidentally expose project secret variables in a job log.
+If you're unsure if it's secure or not, you need to ask security experts for cross-validation.