From b4c88d926e15ce2846b59fcda1aae7f15c8f008c Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Fri, 22 Feb 2019 10:57:54 +0200
Subject: [PATCH 01/21] Update Deps Scanning docs with vendored template

---
 doc/ci/examples/dependency_scanning.md | 125 +++++++++++++++++++------
 1 file changed, 97 insertions(+), 28 deletions(-)

diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md
index 48ddea7320320e..d7ce213ea18d09 100644
--- a/doc/ci/examples/dependency_scanning.md
+++ b/doc/ci/examples/dependency_scanning.md
@@ -1,38 +1,22 @@
 # Dependency Scanning with GitLab CI/CD **[ULTIMATE]**
 
+## Job definition template
+
 CAUTION: **Caution:**
-The job definition shown below is supported on GitLab 11.5 and later versions.
-It also requires the GitLab Runner 11.5 or later.
-For earlier versions, use the [previous job definitions](#previous-job-definitions).
+The CI/CD template for job definition is supported on GitLab 11.9 and later versions.
+For earlier versions, use the [manual job definition](#manual job definition).
 
 This example shows how to run Dependency Scanning on your
 project's dependencies by using GitLab CI/CD.
 
-
 First, you need GitLab Runner with
 [docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor).
 
-Once you set up the Runner, add a new job to `.gitlab-ci.yml` that
-generates the expected report:
+Once you set up the Runner, add a new job to `.gitlab-ci.yml` using [the CI/CD template](https://docs.gitlab.com/ee/ci/yaml/#includetemplate) for Dependency Scanning:
 
 ```yaml
-dependency_scanning:
-  image: docker:stable
-  variables:
-    DOCKER_DRIVER: overlay2
-  allow_failure: true
-  services:
-    - docker:stable-dind
-  script:
-    - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')
-    - docker run
-        --env DEP_SCAN_DISABLE_REMOTE_CHECKS="${DEP_SCAN_DISABLE_REMOTE_CHECKS:-false}"
-        --volume "$PWD:/code"
-        --volume /var/run/docker.sock:/var/run/docker.sock
-        "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$SP_VERSION" /code
-  artifacts:
-    reports:
-      dependency_scanning: gl-dependency-scanning-report.json
+include:
+  template: Dependency-Scanning.gitlab-ci.yml
 ```
 
 The above example will create a `dependency_scanning` job in your CI/CD pipeline
@@ -61,10 +45,87 @@ For [GitLab Ultimate][ee] users, this information will
 be automatically extracted and shown right in the merge request widget.
 [Learn more on Dependency Scanning in merge requests](../../user/project/merge_requests/dependency_scanning.md).
 
+## Job execution customization
+
+### Scanning tool settings
+
+You can customize the execution of the job via settings that can be updated through environment variables. These variables
+are documented in the [template](#job-definition-template) definition and in the Dependency Scanning
+[README](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings).
+
+The customization itself is performed by leveraging the [`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables)
+section in the CI config:
+
+```yaml
+include:
+  template: Dependency-Scanning.gitlab-ci.yml
+
+variables:
+  DEP_SCAN_DISABLE_REMOTE_CHECKS: true
+```
+
+Because template is evaluated [before](https://docs.gitlab.com/ee/ci/yaml/#include) the CI config,
+the last mention of the variable will take precedence.
+
+### Overriding job definition
+
+If you want to override the job definition (change its properties like `variables` or `dependencies`), you need to open
+its definition after the template inclusion and specify any additional keys under it: 
+
+```yaml
+include:
+  template: Dependency-Scanning.gitlab-ci.yml
+
+dependency_scanning:
+  variables:
+    CI_DEBUG_TRACE: "true"
+``` 
+
 ## Supported languages and package managers
 
 See [the full list of supported languages and package managers](../../user/project/merge_requests/dependency_scanning.md#supported-languages-and-dependency-managers).
 
+## Manual job definition
+
+CAUTION: **Caution:**
+The job definition shown below is supported on GitLab 11.5 and later versions _(although it's preferred to use 
+[the job definition template](#job-definition-template) since 11.9)_.
+It also requires the GitLab Runner 11.5 or later.
+For earlier versions, use the [previous job definitions](#previous-job-definitions).
+
+If you are on GitLab prior to 11.9, you can define it manually using the following snippet:
+
+```yaml
+dependency_scanning:
+  image: docker:stable
+  variables:
+    DOCKER_DRIVER: overlay2
+  allow_failure: true
+  services:
+    - docker:stable-dind
+  script:
+    - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')
+    - |
+      docker run \
+      --env DS_ANALYZER_IMAGES \
+      --env DS_ANALYZER_IMAGE_PREFIX \
+      --env DS_ANALYZER_IMAGE_TAG \
+      --env DS_DEFAULT_ANALYZERS \
+      --env DEP_SCAN_DISABLE_REMOTE_CHECKS \
+      --env DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT \
+      --env DS_PULL_ANALYZER_IMAGE_TIMEOUT \
+      --env DS_RUN_ANALYZER_TIMEOUT \
+      --volume "$PWD:/code" \
+      --volume /var/run/docker.sock:/var/run/docker.sock \
+      "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$SP_VERSION" /code
+  artifacts:
+    reports:
+      dependency_scanning: gl-dependency-scanning-report.json
+```
+
+You can supply many other [settings variables](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings)
+via `docker run --env` to customize your job execution.
+
 ## Previous job definitions
 
 CAUTION: **Caution:**
@@ -86,11 +147,19 @@ dependency_scanning:
     - docker:stable-dind
   script:
     - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')
-    - docker run
-        --env DEP_SCAN_DISABLE_REMOTE_CHECKS="${DEP_SCAN_DISABLE_REMOTE_CHECKS:-false}"
-        --volume "$PWD:/code"
-        --volume /var/run/docker.sock:/var/run/docker.sock
-        "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$SP_VERSION" /code
+    - |
+      docker run \
+      --env DS_ANALYZER_IMAGES \
+      --env DS_ANALYZER_IMAGE_PREFIX \
+      --env DS_ANALYZER_IMAGE_TAG \
+      --env DS_DEFAULT_ANALYZERS \
+      --env DEP_SCAN_DISABLE_REMOTE_CHECKS \
+      --env DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT \
+      --env DS_PULL_ANALYZER_IMAGE_TIMEOUT \
+      --env DS_RUN_ANALYZER_TIMEOUT \
+      --volume "$PWD:/code" \
+      --volume /var/run/docker.sock:/var/run/docker.sock \
+      "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$SP_VERSION" /code
   artifacts:
     paths: [gl-dependency-scanning-report.json]
 ```
-- 
GitLab


From 687694d75fdbfd5cec68cce683ecd703a2fde595 Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Mon, 11 Mar 2019 15:07:15 +0000
Subject: [PATCH 02/21] Apply suggestion to
 doc/ci/examples/dependency_scanning.md

---
 doc/ci/examples/dependency_scanning.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md
index d7ce213ea18d09..dbe6ab2bed01fa 100644
--- a/doc/ci/examples/dependency_scanning.md
+++ b/doc/ci/examples/dependency_scanning.md
@@ -49,7 +49,7 @@ be automatically extracted and shown right in the merge request widget.
 
 ### Scanning tool settings
 
-You can customize the execution of the job via settings that can be updated through environment variables. These variables
+You can customize dependency scanning job execution via settings that can be updated through environment variables. These variables
 are documented in the [template](#job-definition-template) definition and in the Dependency Scanning
 [README](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings).
 
-- 
GitLab


From f4b5e57d7e34b111e827db276aa28b2b75205339 Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Mon, 11 Mar 2019 17:23:46 +0200
Subject: [PATCH 03/21] Add an intro for the "Job execution customization"

---
 doc/ci/examples/dependency_scanning.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md
index dbe6ab2bed01fa..2b6d69f83bcf89 100644
--- a/doc/ci/examples/dependency_scanning.md
+++ b/doc/ci/examples/dependency_scanning.md
@@ -47,9 +47,11 @@ be automatically extracted and shown right in the merge request widget.
 
 ## Job execution customization
 
+You can customize dependency scanning job execution in various ways of different granularity.
+
 ### Scanning tool settings
 
-You can customize dependency scanning job execution via settings that can be updated through environment variables. These variables
+Dependency scanning tool settings can be changed through environment variables. These variables
 are documented in the [template](#job-definition-template) definition and in the Dependency Scanning
 [README](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings).
 
-- 
GitLab


From 068ba312572f18fdd2e97a820a51496c91c4493f Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Mon, 11 Mar 2019 17:30:53 +0200
Subject: [PATCH 04/21] Add a list of sources on env variables

---
 doc/ci/examples/dependency_scanning.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md
index 2b6d69f83bcf89..2c3adfcfd3e8d8 100644
--- a/doc/ci/examples/dependency_scanning.md
+++ b/doc/ci/examples/dependency_scanning.md
@@ -51,9 +51,9 @@ You can customize dependency scanning job execution in various ways of different
 
 ### Scanning tool settings
 
-Dependency scanning tool settings can be changed through environment variables. These variables
-are documented in the [template](#job-definition-template) definition and in the Dependency Scanning
-[README](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings).
+Dependency scanning tool settings can be changed through environment variables. These variables are documented in the:                                                                             
+- Job definition [template](#job-definition-template).
+- Dependency Scanning [README](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings).
 
 The customization itself is performed by leveraging the [`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables)
 section in the CI config:
-- 
GitLab


From 1427270f2385adc75e0c315214e4cc521bc18ad1 Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Mon, 11 Mar 2019 15:46:17 +0000
Subject: [PATCH 05/21] Apply suggestion to
 doc/ci/examples/dependency_scanning.md

---
 doc/ci/examples/dependency_scanning.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md
index 2c3adfcfd3e8d8..81fc384c9de133 100644
--- a/doc/ci/examples/dependency_scanning.md
+++ b/doc/ci/examples/dependency_scanning.md
@@ -55,7 +55,7 @@ Dependency scanning tool settings can be changed through environment variables.
 - Job definition [template](#job-definition-template).
 - Dependency Scanning [README](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings).
 
-The customization itself is performed by leveraging the [`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables)
+The customization itself is performed by using the [`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables)
 section in the CI config:
 
 ```yaml
-- 
GitLab


From 2d226a6d837d54da51bc68dce34fa79695cacd33 Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Mon, 11 Mar 2019 15:46:33 +0000
Subject: [PATCH 06/21] Apply suggestion to
 doc/ci/examples/dependency_scanning.md

---
 doc/ci/examples/dependency_scanning.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md
index 81fc384c9de133..39a5c759a5a4c2 100644
--- a/doc/ci/examples/dependency_scanning.md
+++ b/doc/ci/examples/dependency_scanning.md
@@ -56,7 +56,7 @@ Dependency scanning tool settings can be changed through environment variables.
 - Dependency Scanning [README](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings).
 
 The customization itself is performed by using the [`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables)
-section in the CI config:
+parameter in the project's pipeline configuration file (`.gitlab-ci.yml`):
 
 ```yaml
 include:
-- 
GitLab


From 88929fb882260ec678001765df604365016e6640 Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Mon, 11 Mar 2019 15:53:53 +0000
Subject: [PATCH 07/21] Apply suggestion to
 doc/ci/examples/dependency_scanning.md

---
 doc/ci/examples/dependency_scanning.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md
index 39a5c759a5a4c2..9350cb62be9a7d 100644
--- a/doc/ci/examples/dependency_scanning.md
+++ b/doc/ci/examples/dependency_scanning.md
@@ -4,7 +4,7 @@
 
 CAUTION: **Caution:**
 The CI/CD template for job definition is supported on GitLab 11.9 and later versions.
-For earlier versions, use the [manual job definition](#manual job definition).
+For earlier versions, use the [manual job definition](#manual-job-definition).
 
 This example shows how to run Dependency Scanning on your
 project's dependencies by using GitLab CI/CD.
-- 
GitLab


From 7a3f9204e357a41ef49a35ddcb5622bdabc8c5d7 Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Mon, 11 Mar 2019 15:54:29 +0000
Subject: [PATCH 08/21] Apply suggestion to
 doc/ci/examples/dependency_scanning.md

---
 doc/ci/examples/dependency_scanning.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md
index 9350cb62be9a7d..881c55abbf8fbc 100644
--- a/doc/ci/examples/dependency_scanning.md
+++ b/doc/ci/examples/dependency_scanning.md
@@ -66,7 +66,7 @@ variables:
   DEP_SCAN_DISABLE_REMOTE_CHECKS: true
 ```
 
-Because template is evaluated [before](https://docs.gitlab.com/ee/ci/yaml/#include) the CI config,
+Because template is evaluated [before](../yaml/README.md#include) the pipeline configuration,
 the last mention of the variable will take precedence.
 
 ### Overriding job definition
-- 
GitLab


From 1e3eca3905f48755ee303b144e50393b87d5f7c5 Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Mon, 11 Mar 2019 15:54:44 +0000
Subject: [PATCH 09/21] Apply suggestion to
 doc/ci/examples/dependency_scanning.md

---
 doc/ci/examples/dependency_scanning.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md
index 881c55abbf8fbc..b9270a3f327b38 100644
--- a/doc/ci/examples/dependency_scanning.md
+++ b/doc/ci/examples/dependency_scanning.md
@@ -71,7 +71,7 @@ the last mention of the variable will take precedence.
 
 ### Overriding job definition
 
-If you want to override the job definition (change its properties like `variables` or `dependencies`), you need to open
+If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare
 its definition after the template inclusion and specify any additional keys under it: 
 
 ```yaml
-- 
GitLab


From c76c5bcf0519f436038904b6808b58063b9c04b4 Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Mon, 11 Mar 2019 15:54:55 +0000
Subject: [PATCH 10/21] Apply suggestion to
 doc/ci/examples/dependency_scanning.md

---
 doc/ci/examples/dependency_scanning.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md
index b9270a3f327b38..34fa327ad87646 100644
--- a/doc/ci/examples/dependency_scanning.md
+++ b/doc/ci/examples/dependency_scanning.md
@@ -72,7 +72,7 @@ the last mention of the variable will take precedence.
 ### Overriding job definition
 
 If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare
-its definition after the template inclusion and specify any additional keys under it: 
+its definition after the template inclusion and specify any additional keys under it. For example:
 
 ```yaml
 include:
-- 
GitLab


From a2c94f20e8827c7b358d571fc6d9d541ff6f56c1 Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Mon, 11 Mar 2019 15:55:14 +0000
Subject: [PATCH 11/21] Apply suggestion to
 doc/ci/examples/dependency_scanning.md

---
 doc/ci/examples/dependency_scanning.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md
index 34fa327ad87646..22e5dc050015d7 100644
--- a/doc/ci/examples/dependency_scanning.md
+++ b/doc/ci/examples/dependency_scanning.md
@@ -95,7 +95,7 @@ The job definition shown below is supported on GitLab 11.5 and later versions _(
 It also requires the GitLab Runner 11.5 or later.
 For earlier versions, use the [previous job definitions](#previous-job-definitions).
 
-If you are on GitLab prior to 11.9, you can define it manually using the following snippet:
+If you are using GitLab prior to 11.9, you can define it manually using the following snippet:
 
 ```yaml
 dependency_scanning:
-- 
GitLab


From 7e4a00023d94c69a7ed20f1ef165bb9be10dbe54 Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Tue, 12 Mar 2019 12:55:17 +0200
Subject: [PATCH 12/21] Restructure the Deps Scanning example doc

---
 doc/ci/examples/dependency_scanning.md | 42 ++++++++++++++++----------
 1 file changed, 26 insertions(+), 16 deletions(-)

diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md
index 22e5dc050015d7..6e4130693cd03c 100644
--- a/doc/ci/examples/dependency_scanning.md
+++ b/doc/ci/examples/dependency_scanning.md
@@ -1,17 +1,23 @@
 # Dependency Scanning with GitLab CI/CD **[ULTIMATE]**
 
-## Job definition template
+These examples show how to run Dependency Scanning on your project's dependencies by using GitLab CI/CD.
+
+## Prerequisites
+
+To run a dependency scanning job, you need GitLab Runner with
+[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor).
+
+## Configuring with templates 
+
+Since GitLab 11.9, a CI/CD template with the default dependency scanning job definition is provided as a part of your GitLab installation.
+This section describes how to use it and customize its execution.
+
+### Using job definition template
 
 CAUTION: **Caution:**
 The CI/CD template for job definition is supported on GitLab 11.9 and later versions.
 For earlier versions, use the [manual job definition](#manual-job-definition).
 
-This example shows how to run Dependency Scanning on your
-project's dependencies by using GitLab CI/CD.
-
-First, you need GitLab Runner with
-[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor).
-
 Once you set up the Runner, add a new job to `.gitlab-ci.yml` using [the CI/CD template](https://docs.gitlab.com/ee/ci/yaml/#includetemplate) for Dependency Scanning:
 
 ```yaml
@@ -19,6 +25,8 @@ include:
   template: Dependency-Scanning.gitlab-ci.yml
 ```
 
+### Scanning results
+
 The above example will create a `dependency_scanning` job in your CI/CD pipeline
 and scan your dependencies for possible vulnerabilities. The report will be saved as a
 [Dependency Scanning report artifact](../../ci/yaml/README.md#artifactsreportsdependency_scanning-ultimate)
@@ -38,20 +46,22 @@ is used to detect the languages/package managers and in turn runs the matching s
 
 Some security scanners require to send a list of project dependencies to GitLab
 central servers to check for vulnerabilities. To learn more about this or to
-disable it, check the [GitLab Dependency Scanning documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks).
+disable it, check the [GitLab Dependency Scanning documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks)
+and the [customization guide](#job-execution-customization).
 
 TIP: **Tip:**
 For [GitLab Ultimate][ee] users, this information will
 be automatically extracted and shown right in the merge request widget.
 [Learn more on Dependency Scanning in merge requests](../../user/project/merge_requests/dependency_scanning.md).
 
-## Job execution customization
+### Customizing the template
 
 You can customize dependency scanning job execution in various ways of different granularity.
 
-### Scanning tool settings
+#### Scanning tool settings
 
-Dependency scanning tool settings can be changed through environment variables. These variables are documented in the:                                                                             
+Dependency scanning tool settings can be changed through environment variables. These variables are documented in the:
+                                                                             
 - Job definition [template](#job-definition-template).
 - Dependency Scanning [README](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings).
 
@@ -69,7 +79,7 @@ variables:
 Because template is evaluated [before](../yaml/README.md#include) the pipeline configuration,
 the last mention of the variable will take precedence.
 
-### Overriding job definition
+#### Overriding job definition
 
 If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare
 its definition after the template inclusion and specify any additional keys under it. For example:
@@ -83,10 +93,6 @@ dependency_scanning:
     CI_DEBUG_TRACE: "true"
 ``` 
 
-## Supported languages and package managers
-
-See [the full list of supported languages and package managers](../../user/project/merge_requests/dependency_scanning.md#supported-languages-and-dependency-managers).
-
 ## Manual job definition
 
 CAUTION: **Caution:**
@@ -166,4 +172,8 @@ dependency_scanning:
     paths: [gl-dependency-scanning-report.json]
 ```
 
+## Supported languages and package managers
+
+See [the full list of supported languages and package managers](../../user/project/merge_requests/dependency_scanning.md#supported-languages-and-dependency-managers).
+
 [ee]: https://about.gitlab.com/pricing/
-- 
GitLab


From 5a7fb47663f12e5472e998c4a2d77d592331643c Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Thu, 14 Mar 2019 11:25:52 +0200
Subject: [PATCH 13/21] Fix minor errors in Dependency Scanning example

---
 doc/ci/examples/dependency_scanning.md | 25 +++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md
index 6e4130693cd03c..3e608273b88480 100644
--- a/doc/ci/examples/dependency_scanning.md
+++ b/doc/ci/examples/dependency_scanning.md
@@ -4,12 +4,12 @@ These examples show how to run Dependency Scanning on your project's dependencie
 
 ## Prerequisites
 
-To run a dependency scanning job, you need GitLab Runner with
+To run a Dependency Scanning job, you need GitLab Runner with
 [docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor).
 
-## Configuring with templates 
+## Configuring with templates
 
-Since GitLab 11.9, a CI/CD template with the default dependency scanning job definition is provided as a part of your GitLab installation.
+Since GitLab 11.9, a CI/CD template with the default Dependency Scanning job definition is provided as a part of your GitLab installation.
 This section describes how to use it and customize its execution.
 
 ### Using job definition template
@@ -18,7 +18,7 @@ CAUTION: **Caution:**
 The CI/CD template for job definition is supported on GitLab 11.9 and later versions.
 For earlier versions, use the [manual job definition](#manual-job-definition).
 
-Once you set up the Runner, add a new job to `.gitlab-ci.yml` using [the CI/CD template](https://docs.gitlab.com/ee/ci/yaml/#includetemplate) for Dependency Scanning:
+Once you set up the Runner, add a new job to `.gitlab-ci.yml` using [the CI/CD template](../../ci/yaml/README.md#includetemplate) for Dependency Scanning:
 
 ```yaml
 include:
@@ -56,13 +56,13 @@ be automatically extracted and shown right in the merge request widget.
 
 ### Customizing the template
 
-You can customize dependency scanning job execution in various ways of different granularity.
+You can customize Dependency Scanning job execution in various ways of different granularity.
 
 #### Scanning tool settings
 
-Dependency scanning tool settings can be changed through environment variables. These variables are documented in the:
+Dependency Scanning tool settings can be changed through environment variables. These variables are documented in the:
                                                                              
-- Job definition [template](#job-definition-template).
+- Job definition [template](#using-job-definition-template).
 - Dependency Scanning [README](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings).
 
 The customization itself is performed by using the [`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables)
@@ -97,7 +97,7 @@ dependency_scanning:
 
 CAUTION: **Caution:**
 The job definition shown below is supported on GitLab 11.5 and later versions _(although it's preferred to use 
-[the job definition template](#job-definition-template) since 11.9)_.
+[the job definition template](#using-job-definition-template) since 11.9)_.
 It also requires the GitLab Runner 11.5 or later.
 For earlier versions, use the [previous job definitions](#previous-job-definitions).
 
@@ -112,7 +112,7 @@ dependency_scanning:
   services:
     - docker:stable-dind
   script:
-    - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')
+    - export DS_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')}
     - |
       docker run \
       --env DS_ANALYZER_IMAGES \
@@ -125,7 +125,8 @@ dependency_scanning:
       --env DS_RUN_ANALYZER_TIMEOUT \
       --volume "$PWD:/code" \
       --volume /var/run/docker.sock:/var/run/docker.sock \
-      "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$SP_VERSION" /code
+      "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$DS_VERSION" /code
+  dependencies: []
   artifacts:
     reports:
       dependency_scanning: gl-dependency-scanning-report.json
@@ -154,7 +155,7 @@ dependency_scanning:
   services:
     - docker:stable-dind
   script:
-    - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')
+    - export DS_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')}
     - |
       docker run \
       --env DS_ANALYZER_IMAGES \
@@ -167,7 +168,7 @@ dependency_scanning:
       --env DS_RUN_ANALYZER_TIMEOUT \
       --volume "$PWD:/code" \
       --volume /var/run/docker.sock:/var/run/docker.sock \
-      "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$SP_VERSION" /code
+      "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$DS_VERSION" /code
   artifacts:
     paths: [gl-dependency-scanning-report.json]
 ```
-- 
GitLab


From 13a625dcd1a39ece20bb2d5e227c05dc856f741c Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Thu, 14 Mar 2019 11:26:25 +0200
Subject: [PATCH 14/21] Update SAST example with vendored template info

---
 doc/ci/examples/sast.md | 135 +++++++++++++++++++++++++++++++---------
 1 file changed, 104 insertions(+), 31 deletions(-)

diff --git a/doc/ci/examples/sast.md b/doc/ci/examples/sast.md
index 2c9db74b9b99a3..37158067d31dfa 100644
--- a/doc/ci/examples/sast.md
+++ b/doc/ci/examples/sast.md
@@ -1,40 +1,33 @@
 # Static Application Security Testing with GitLab CI/CD **[ULTIMATE]**
 
-CAUTION: **Caution:**
-The job definition shown below is supported on GitLab 11.5 and later versions.
-It also requires the GitLab Runner 11.5 or later.
-For earlier versions, use the [previous job definitions](#previous-job-definitions).
-
-This example shows how to run
-[Static Application Security Testing (SAST)](https://en.wikipedia.org/wiki/Static_program_analysis)
+These examples show how to run [Static Application Security Testing (SAST)](https://en.wikipedia.org/wiki/Static_program_analysis)
 on your project's source code by using GitLab CI/CD.
 
-First, you need GitLab Runner with
+## Prerequisites
+
+To run a SAST job, you need GitLab Runner with
 [docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor).
 
-Once you set up the Runner, add a new job to `.gitlab-ci.yml` that
-generates the expected report:
+## Configuring with templates
+
+Since GitLab 11.9, a CI/CD template with the default SAST job definition is provided as a part of your GitLab installation.
+This section describes how to use it and customize its execution.
+
+### Using job definition template
+
+CAUTION: **Caution:**
+The CI/CD template for job definition is supported on GitLab 11.9 and later versions.
+For earlier versions, use the [manual job definition](#manual-job-definition).
+
+Once you set up the Runner, add a new job to `.gitlab-ci.yml` using [the CI/CD template](../../ci/yaml/README.md#includetemplate) for SAST:
 
 ```yaml
-sast:
-  image: docker:stable
-  variables:
-    DOCKER_DRIVER: overlay2
-  allow_failure: true
-  services:
-    - docker:stable-dind
-  script:
-    - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')
-    - docker run
-        --env SAST_CONFIDENCE_LEVEL="${SAST_CONFIDENCE_LEVEL:-3}"
-        --volume "$PWD:/code"
-        --volume /var/run/docker.sock:/var/run/docker.sock
-        "registry.gitlab.com/gitlab-org/security-products/sast:$SP_VERSION" /app/bin/run /code
-  artifacts:
-    reports:
-      sast: gl-sast-report.json
+include:
+  template: SAST.gitlab-ci.yml
 ```
 
+### Scanning results
+
 The above example will create a `sast` job in your CI/CD pipeline
 and scan your dependencies for possible vulnerabilities. The report will be saved as a
 [SAST report artifact](../../ci/yaml/README.md#artifactsreportssast-ultimate)
@@ -58,9 +51,89 @@ For [GitLab Ultimate][ee] users, this information will
 be automatically extracted and shown right in the merge request widget.
 [Learn more on SAST in merge requests](../../user/project/merge_requests/sast.md).
 
-## Supported languages and frameworks
+### Customizing the template
+
+You can customize SAST job execution in various ways of different granularity.
+
+#### Scanning tool settings
+
+SAST tool settings can be changed through environment variables. These variables are documented in the:
+                                                                             
+- Job definition [template](#using-job-definition-template).
+- Dependency Scanning [README](https://gitlab.com/gitlab-org/security-products/sast#settings).
+
+The customization itself is performed by using the [`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables)
+parameter in the project's pipeline configuration file (`.gitlab-ci.yml`):
+
+```yaml
+include:
+  template: SAST.gitlab-ci.yml
+
+variables:
+  SAST_GOSEC_LEVEL: 2
+```
+
+Because template is evaluated [before](../yaml/README.md#include) the pipeline configuration,
+the last mention of the variable will take precedence.
+
+#### Overriding job definition
+
+If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare
+its definition after the template inclusion and specify any additional keys under it. For example:
+
+```yaml
+include:
+  template: SAST.gitlab-ci.yml
+
+sast:
+  variables:
+    CI_DEBUG_TRACE: "true"
+``` 
+
+## Manual job definition
+
+CAUTION: **Caution:**
+The job definition shown below is supported on GitLab 11.5 and later versions _(although it's preferred to use 
+[the job definition template](#using-job-definition-template) since 11.9)_.
+It also requires the GitLab Runner 11.5 or later.
+For earlier versions, use the [previous job definitions](#previous-job-definitions).
+
+If you are using GitLab prior to 11.9, you can define it manually using the following snippet:
+
+```yaml
+sast:
+  stage: test
+  image: docker:stable
+  variables:
+    DOCKER_DRIVER: overlay2
+  allow_failure: true
+  services:
+    - docker:stable-dind
+  script:
+    - export SAST_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')}
+    - |
+      docker run \
+        --env SAST_ANALYZER_IMAGES \
+        --env SAST_ANALYZER_IMAGE_PREFIX \
+        --env SAST_ANALYZER_IMAGE_TAG \
+        --env SAST_DEFAULT_ANALYZERS \
+        --env SAST_BRAKEMAN_LEVEL \
+        --env SAST_GOSEC_LEVEL \
+        --env SAST_FLAWFINDER_LEVEL \
+        --env SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT \
+        --env SAST_PULL_ANALYZER_IMAGE_TIMEOUT \
+        --env SAST_RUN_ANALYZER_TIMEOUT \
+        --volume "$PWD:/code" \
+        --volume /var/run/docker.sock:/var/run/docker.sock \
+        "registry.gitlab.com/gitlab-org/security-products/sast:$SAST_VERSION" /app/bin/run /code
+  dependencies: []
+  artifacts:
+    reports:
+      sast: gl-sast-report.json
+```
 
-See [the full list of supported languages and frameworks](../../user/project/merge_requests/sast.md#supported-languages-and-frameworks).
+You can supply many other [settings variables](https://gitlab.com/gitlab-org/security-products/sast#settings)
+via `docker run --env` to customize your job execution.
 
 ## Previous job definitions
 
@@ -82,12 +155,12 @@ sast:
   services:
     - docker:stable-dind
   script:
-    - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')
+    - export SAST_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')}
     - docker run
         --env SAST_CONFIDENCE_LEVEL="${SAST_CONFIDENCE_LEVEL:-3}"
         --volume "$PWD:/code"
         --volume /var/run/docker.sock:/var/run/docker.sock
-        "registry.gitlab.com/gitlab-org/security-products/sast:$SP_VERSION" /app/bin/run /code
+        "registry.gitlab.com/gitlab-org/security-products/sast:$SAST_VERSION" /app/bin/run /code
   artifacts:
     paths: [gl-sast-report.json]
 ```
-- 
GitLab


From 7826f3acbd39247c89ac914eacea83bb90d855f5 Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Thu, 14 Mar 2019 12:00:21 +0200
Subject: [PATCH 15/21] Improve dind executor links for DS and SAST docs

---
 doc/ci/examples/dependency_scanning.md | 2 +-
 doc/ci/examples/sast.md                | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md
index 3e608273b88480..87f8f8f0ec5e17 100644
--- a/doc/ci/examples/dependency_scanning.md
+++ b/doc/ci/examples/dependency_scanning.md
@@ -5,7 +5,7 @@ These examples show how to run Dependency Scanning on your project's dependencie
 ## Prerequisites
 
 To run a Dependency Scanning job, you need GitLab Runner with
-[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor).
+[docker-in-docker executor](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode).
 
 ## Configuring with templates
 
diff --git a/doc/ci/examples/sast.md b/doc/ci/examples/sast.md
index 37158067d31dfa..3c8f1e2ee4638e 100644
--- a/doc/ci/examples/sast.md
+++ b/doc/ci/examples/sast.md
@@ -6,7 +6,7 @@ on your project's source code by using GitLab CI/CD.
 ## Prerequisites
 
 To run a SAST job, you need GitLab Runner with
-[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor).
+[docker-in-docker executor](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode).
 
 ## Configuring with templates
 
-- 
GitLab


From 84353457fa70398561e8fa58209c347f215f6da6 Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Thu, 14 Mar 2019 14:21:59 +0200
Subject: [PATCH 16/21] Fix: remove copy-paste artifacts from SAST example

---
 doc/ci/examples/sast.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/ci/examples/sast.md b/doc/ci/examples/sast.md
index 3c8f1e2ee4638e..d55e1d11e3f45d 100644
--- a/doc/ci/examples/sast.md
+++ b/doc/ci/examples/sast.md
@@ -29,7 +29,7 @@ include:
 ### Scanning results
 
 The above example will create a `sast` job in your CI/CD pipeline
-and scan your dependencies for possible vulnerabilities. The report will be saved as a
+and scan your project's source code for possible vulnerabilities. The report will be saved as a
 [SAST report artifact](../../ci/yaml/README.md#artifactsreportssast-ultimate)
 that you can later download and analyze.
 Due to implementation limitations we always take the latest SAST artifact available.
@@ -60,7 +60,7 @@ You can customize SAST job execution in various ways of different granularity.
 SAST tool settings can be changed through environment variables. These variables are documented in the:
                                                                              
 - Job definition [template](#using-job-definition-template).
-- Dependency Scanning [README](https://gitlab.com/gitlab-org/security-products/sast#settings).
+- SAST [README](https://gitlab.com/gitlab-org/security-products/sast#settings).
 
 The customization itself is performed by using the [`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables)
 parameter in the project's pipeline configuration file (`.gitlab-ci.yml`):
-- 
GitLab


From 3698a7a41ed4df9b35ba4285a40cdff611f7c34a Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Thu, 14 Mar 2019 14:23:28 +0200
Subject: [PATCH 17/21] Update DAST example with vendored template info

---
 doc/ci/examples/dast.md | 133 +++++++++++++++++++++++++++++++++-------
 1 file changed, 110 insertions(+), 23 deletions(-)

diff --git a/doc/ci/examples/dast.md b/doc/ci/examples/dast.md
index 52c4147e245351..c9506cf3f02a46 100644
--- a/doc/ci/examples/dast.md
+++ b/doc/ci/examples/dast.md
@@ -1,11 +1,6 @@
 # Dynamic Application Security Testing with GitLab CI/CD
 
-CAUTION: **Caution:**
-The job definition shown below is supported on GitLab 11.5 and later versions.
-It also requires the GitLab Runner 11.5 or later.
-For earlier versions, use the [previous job definitions](#previous-job-definitions).
-
-[Dynamic Application Security Testing (DAST)](https://en.wikipedia.org/wiki/Dynamic_program_analysis)
+[Dynamic Application Security Testing (DAST)](https://en.wikipedia.org/wiki/Dynamic_Application_Security_Testing)
 is using the popular open source tool [OWASP ZAProxy](https://github.com/zaproxy/zaproxy)
 to perform an analysis on your running web application.
 Since it is based on [ZAP Baseline](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan)
@@ -14,13 +9,114 @@ it will not actively attack your application.
 
 It can be very useful combined with [Review Apps](../review_apps/index.md).
 
-## Example
+These examples show how to run DAST on your running web application by using GitLab CI/CD.
+
+## Prerequisites
 
-First, you need GitLab Runner with
+To run a DAST job, you need GitLab Runner with
 [docker executor](https://docs.gitlab.com/runner/executors/docker.html).
 
-Once you set up the Runner, add a new job to `.gitlab-ci.yml` that
-generates the expected report:
+## Configuring with templates
+
+Since GitLab 11.9, a CI/CD template with the default DAST job definition is provided as a part of your GitLab installation.
+This section describes how to use it and customize its execution.
+
+### Using job definition template
+
+CAUTION: **Caution:**
+The CI/CD template for job definition is supported on GitLab 11.9 and later versions.
+For earlier versions, use the [manual job definition](#manual-job-definition).
+
+Once you set up the Runner, add a new job to `.gitlab-ci.yml` using [the CI/CD template](../../ci/yaml/README.md#includetemplate) for DAST:
+
+```yaml
+include:
+  template: DAST.gitlab-ci.yml
+```
+
+The above example will create a `dast` job in your CI/CD pipeline which will run
+the tests on the URL defined in the `DAST_WEBSITE` variable (change it to use your
+own) and scan it for possible vulnerabilities.
+
+It's also possible to authenticate the user before performing DAST checks:
+
+```yaml
+include:
+  template: DAST.gitlab-ci.yml
+  
+variables:
+  DAST_AUTH_URL: https://example.com/sign-in
+  DAST_USERNAME: john.doe@example.com
+  DAST_PASSWORD: john-doe-password
+  DAST_USERNAME_FIELD: session[user] # the name of username field at the sign-in HTML form
+  DAST_PASSWORD_FIELD: session[password] # the name of password field at the sign-in HTML form
+```
+
+### Scanning results
+
+The report will be saved as a
+[DAST report artifact](../yaml/README.md#artifactsreportsdast-ultimate)
+that you can later download and analyze.
+Due to implementation limitations we always take the latest DAST artifact available.
+
+TIP: **Tip:**
+For [GitLab Ultimate][ee] users, this information will
+be automatically extracted and shown right in the merge request widget.
+[Learn more on DAST in merge requests](../../user/project/merge_requests/dast.md).
+
+### Customizing the template
+
+You can customize DAST job execution in various ways of different granularity.
+
+#### Scanning tool settings
+
+DAST tool settings can be changed through environment variables. These variables are documented in the:
+                                                                             
+- Job definition [template](#using-job-definition-template).
+- DAST [README](https://gitlab.com/gitlab-org/security-products/dast#settings).
+
+The customization itself is performed by using the [`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables)
+parameter in the project's pipeline configuration file (`.gitlab-ci.yml`):
+
+```yaml
+include:
+  template: DAST.gitlab-ci.yml
+
+variables:
+  DAST_TARGET_AVAILABILITY_TIMEOUT: 120
+```
+
+Because template is evaluated [before](../yaml/README.md#include) the pipeline configuration,
+the last mention of the variable will take precedence.
+
+#### Overriding job definition
+
+If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare
+its definition after the template inclusion and specify any additional keys under it. For example:
+
+```yaml
+include:
+  template: DAST.gitlab-ci.yml
+
+dast:
+  stage: dast # IMPORTANT: don't forget to add this
+  variables:
+    CI_DEBUG_TRACE: "true"
+``` 
+
+CAUTION: **Caution:**
+As DAST job belongs to a separate `"dast"` stage that runs after all [default stages](../yaml/README.md#stages),
+don't forget to add `stage: dast` entry when you override the template job definition. 
+
+## Manual job definition
+
+CAUTION: **Caution:**
+The job definition shown below is supported on GitLab 11.5 and later versions _(although it's preferred to use 
+[the job definition template](#using-job-definition-template) since 11.9)_.
+It also requires the GitLab Runner 11.5 or later.
+For earlier versions, use the [previous job definitions](#previous-job-definitions).
+
+If you are using GitLab prior to 11.9, you can define it manually using the following snippet:
 
 ```yaml
 dast:
@@ -37,14 +133,9 @@ dast:
       dast: gl-dast-report.json
 ```
 
-The above example will create a `dast` job in your CI/CD pipeline which will run
-the tests on the URL defined in the `website` variable (change it to use your
-own) and scan it for possible vulnerabilities. The report will be saved as a
-[DAST report artifact](../yaml/README.md#artifactsreportsdast-ultimate)
-that you can later download and analyze.
-Due to implementation limitations we always take the latest DAST artifact available.
+where the `website` variable is supposed to hold the URL to run the tests against.
 
-It's also possible to authenticate the user before performing DAST checks:
+For an authenticated scan, use the following definition:
 
 ```yaml
 dast:
@@ -66,14 +157,10 @@ dast:
     reports:
       dast: gl-dast-report.json
 ```
+
 See [zaproxy documentation](https://gitlab.com/gitlab-org/security-products/zaproxy)
 to learn more about authentication settings.
 
-TIP: **Tip:**
-For [GitLab Ultimate][ee] users, this information will
-be automatically extracted and shown right in the merge request widget.
-[Learn more on DAST in merge requests](../../user/project/merge_requests/dast.md).
-
 ## Previous job definitions
 
 CAUTION: **Caution:**
@@ -97,6 +184,6 @@ dast:
     - cp /zap/wrk/gl-dast-report.json .
   artifacts:
     paths: [gl-dast-report.json]
-```
+``` 
 
 [ee]: https://about.gitlab.com/pricing/
-- 
GitLab


From 12f102de5976e9118fac68739b91cb50d3baa241 Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Thu, 14 Mar 2019 14:28:51 +0200
Subject: [PATCH 18/21] Add missing Ultimate tag to CS example

---
 doc/ci/examples/container_scanning.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/ci/examples/container_scanning.md b/doc/ci/examples/container_scanning.md
index 5ef41d498cc0f7..2458076351825f 100644
--- a/doc/ci/examples/container_scanning.md
+++ b/doc/ci/examples/container_scanning.md
@@ -1,4 +1,4 @@
-# Container Scanning with GitLab CI/CD
+# Container Scanning with GitLab CI/CD **[ULTIMATE]**
 
 CAUTION: **Caution:**
 The job definition shown below is supported on GitLab 11.5 and later versions.
-- 
GitLab


From b3397a25dc6de48bad5ff8dea182d344fb41d51d Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Thu, 14 Mar 2019 14:54:42 +0200
Subject: [PATCH 19/21] Add vendored template info to Container Scanning

---
 doc/ci/examples/container_scanning.md | 96 ++++++++++++++++++---------
 1 file changed, 63 insertions(+), 33 deletions(-)

diff --git a/doc/ci/examples/container_scanning.md b/doc/ci/examples/container_scanning.md
index 2458076351825f..7c5031a3989d57 100644
--- a/doc/ci/examples/container_scanning.md
+++ b/doc/ci/examples/container_scanning.md
@@ -1,20 +1,73 @@
 # Container Scanning with GitLab CI/CD **[ULTIMATE]**
 
-CAUTION: **Caution:**
-The job definition shown below is supported on GitLab 11.5 and later versions.
-It also requires the GitLab Runner 11.5 or later.
-For earlier versions, use the [previous job definitions](#previous-job-definitions).
-
 You can check your Docker images (or more precisely the containers) for known
 vulnerabilities by using [Clair](https://github.com/coreos/clair) and
 [clair-scanner](https://github.com/arminc/clair-scanner), two open source tools
 for Vulnerability Static Analysis for containers.
 
-First, you need GitLab Runner with
-[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor).
+These examples show how to run Container Scanning on your Docker image by using GitLab CI/CD.
+
+CAUTION: **Caution:**
+Starting with GitLab 11.5, Container Scanning feature is licensed under the name `container_scanning`.
+While the old name `sast_container` is still maintained, it has been deprecated with GitLab 11.5 and
+may be removed in next major release, GitLab 12.0. You are advised to update your current `.gitlab-ci.yml`
+configuration to reflect that change if you are using the `$GITLAB_FEATURES` environment variable.
+
+## Prerequisites
+
+To run a Container Scanning job, you need:
+
+- a GitLab Runner with
+[docker-in-docker executor](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode).
+- to [build and push](../../ci/docker/using_docker_build.md#container-registry-examples) your Docker image
+using the [Container Registry](https://docs.gitlab.com/ee/user/project/container_registry.html) running within your GitLab installation.
+
+## Configuring with templates
+
+Since GitLab 11.9, a CI/CD template with the default Container Scanning job definition is provided as a part of your GitLab installation.
+This section describes how to use it and customize its execution.
+
+### Using job definition template
+
+CAUTION: **Caution:**
+The CI/CD template for job definition is supported on GitLab 11.9 and later versions.
+For earlier versions, use the [manual job definition](#manual-job-definition).
+
+Once you set up the Runner, add a new job to `.gitlab-ci.yml` using [the CI/CD template](../../ci/yaml/README.md#includetemplate) for Container Scanning:
+
+```yaml
+include:
+  template: Container-Scanning.gitlab-ci.yml
+```
+
+If you want to whitelist some specific vulnerabilities, you can do so by defining
+them in a [YAML file](https://github.com/arminc/clair-scanner/blob/master/README.md#example-whitelist-yaml-file),
+in our case its named `clair-whitelist.yml`.
+
+### Scanning results
+
+The above example will create a `container_scanning` job in your CI/CD pipeline, pull
+the image from the [Container Registry](../../user/project/container_registry.md)
+(whose name is defined from the two `CI_APPLICATION_` variables) and scan it
+for possible vulnerabilities. The report will be saved as a
+[Container Scanning report artifact](../yaml/README.md#artifactsreportscontainer_scanning-ultimate)
+that you can later download and analyze.
+Due to implementation limitations we always take the latest Container Scanning artifact available.
+
+TIP: **Tip:**
+For [GitLab Ultimate][ee] users, this information will
+be automatically extracted and shown right in the merge request widget.
+[Learn more on Container Scanning in merge requests](../../user/project/merge_requests/container_scanning.html).
 
-Once you set up the Runner, add a new job to `.gitlab-ci.yml` that
-generates the expected report:
+## Manual job definition
+
+CAUTION: **Caution:**
+The job definition shown below is supported on GitLab 11.5 and later versions _(although it's preferred to use 
+[the job definition template](#using-job-definition-template) since 11.9)_.
+It also requires the GitLab Runner 11.5 or later.
+For earlier versions, use the [previous job definitions](#previous-job-definitions).
+
+If you are using GitLab prior to 11.9, you can define it manually using the following snippet:
 
 ```yaml
 container_scanning:
@@ -47,29 +100,6 @@ container_scanning:
       container_scanning: gl-container-scanning-report.json
 ```
 
-The above example will create a `container_scanning` job in your CI/CD pipeline, pull
-the image from the [Container Registry](../../user/project/container_registry.md)
-(whose name is defined from the two `CI_APPLICATION_` variables) and scan it
-for possible vulnerabilities. The report will be saved as a
-[Container Scanning report artifact](../yaml/README.md#artifactsreportscontainer_scanning-ultimate)
-that you can later download and analyze.
-Due to implementation limitations we always take the latest Container Scanning artifact available.
-
-If you want to whitelist some specific vulnerabilities, you can do so by defining
-them in a [YAML file](https://github.com/arminc/clair-scanner/blob/master/README.md#example-whitelist-yaml-file),
-in our case its named `clair-whitelist.yml`.
-
-TIP: **Tip:**
-For [GitLab Ultimate][ee] users, this information will
-be automatically extracted and shown right in the merge request widget.
-[Learn more on Container Scanning in merge requests](../../user/project/merge_requests/container_scanning.html).
-
-CAUTION: **Caution:**
-Starting with GitLab 11.5, Container Scanning feature is licensed under the name `container_scanning`.
-While the old name `sast_container` is still maintained, it has been deprecated with GitLab 11.5 and
-may be removed in next major release, GitLab 12.0. You are advised to update your current `.gitlab-ci.yml`
-configuration to reflect that change if you are using the `$GITLAB_FEATURES` environment variable.
-
 ## Previous job definitions
 
 CAUTION: **Caution:**
@@ -111,7 +141,7 @@ container_scanning:
     paths: [gl-container-scanning-report.json]
 ```
 
-Alternatively the job name could be `sast:container`
+Alternatively, the job name could be `sast:container`
 and the artifact name could be `gl-sast-container-report.json`.
 These names have been deprecated with GitLab 11.0
 and may be removed in next major release, GitLab 12.0.
-- 
GitLab


From b4db6512541904af03afffa3722001ee6ea7fe13 Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Thu, 14 Mar 2019 17:05:42 +0200
Subject: [PATCH 20/21] Remove extra space in DS example

---
 doc/ci/examples/dependency_scanning.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md
index 87f8f8f0ec5e17..3b3cafc39b4f73 100644
--- a/doc/ci/examples/dependency_scanning.md
+++ b/doc/ci/examples/dependency_scanning.md
@@ -91,7 +91,7 @@ include:
 dependency_scanning:
   variables:
     CI_DEBUG_TRACE: "true"
-``` 
+```
 
 ## Manual job definition
 
-- 
GitLab


From 66b09d88dac9a4594e2daf398abd1a7ac1bceaf2 Mon Sep 17 00:00:00 2001
From: Victor Zagorodny <vzagorodny@gitlab.com>
Date: Thu, 14 Mar 2019 17:07:15 +0200
Subject: [PATCH 21/21] Add vendored template info to License Management

---
 doc/ci/examples/license_management.md | 106 +++++++++++++++++++-------
 1 file changed, 77 insertions(+), 29 deletions(-)

diff --git a/doc/ci/examples/license_management.md b/doc/ci/examples/license_management.md
index c45f1c0404ab1e..ab78b3c0b53ac5 100644
--- a/doc/ci/examples/license_management.md
+++ b/doc/ci/examples/license_management.md
@@ -1,40 +1,46 @@
 # Dependencies license management with GitLab CI/CD **[ULTIMATE]**
 
-CAUTION: **Caution:**
-The job definition shown below is supported on GitLab 11.5 and later versions.
-It also requires the GitLab Runner 11.5 or later.
-For earlier versions, use the [previous job definitions](#previous-job-definitions).
+These examples show how to run License Management scanning on your project's dependencies by using GitLab CI/CD.
+
+## Prerequisites
+
+To run a License Management scanning job, you need GitLab Runner with
+[docker executor](https://docs.gitlab.com/runner/executors/docker.html).
 
-This example shows how to run the License Management tool on your
-project's dependencies by using GitLab CI/CD.
+## Configuring with templates
 
-First, you need GitLab Runner with
-[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor).
+Since GitLab 11.9, a CI/CD template with the default License Management scanning job definition is provided as a part of your GitLab installation.
+This section describes how to use it and customize its execution.
 
-Once you set up the Runner, add a new job to `.gitlab-ci.yml` that
-generates the expected report:
+### Using job definition template
+
+CAUTION: **Caution:**
+The CI/CD template for job definition is supported on GitLab 11.9 and later versions.
+For earlier versions, use the [manual job definition](#manual-job-definition).
+
+Once you set up the Runner, add a new job to `.gitlab-ci.yml` using [the CI/CD template](../../ci/yaml/README.md#includetemplate) for License Management:
 
 ```yaml
-license_management:
-  image:
-    name: "registry.gitlab.com/gitlab-org/security-products/license-management:$CI_SERVER_VERSION_MAJOR-$CI_SERVER_VERSION_MINOR-stable"
-    entrypoint: [""]
-  stage: test
-  allow_failure: true
-  script:
-    - /run.sh analyze .
-  artifacts:
-    reports:
-      license_management: gl-license-management-report.json
+include:
+  template: License-Management.gitlab-ci.yml
 ```
 
+### Scanning results
+
 The above example will create a `license_management` job in your CI/CD pipeline
 and scan your dependencies to find their licenses. The report will be saved as a
 [License Management report artifact](../../ci/yaml/README.md#artifactsreportslicense_management-ultimate)
 that you can later download and analyze.
 Due to implementation limitations we always take the latest License Management artifact available.
 
-## Install custom project dependencies
+TIP: **Tip:**
+For [GitLab Ultimate][ee] users, this information will
+be automatically extracted and shown right in the merge request widget.
+[Learn more on License Management in merge requests](../../user/project/merge_requests/license_management.md).
+
+### Customizing the template
+
+#### Install custom project dependencies
 
 > Introduced in GitLab Ultimate 11.4.
 
@@ -50,14 +56,45 @@ of your application (ex: for a project with a `Gemfile`, the setup step will be
 
 Example:
 
+```yaml
+include:
+  template: License-Management.gitlab-ci.yml
+  
+variables:
+  LICENSE_MANAGEMENT_SETUP_CMD: ./my-custom-install-script.sh
+```
+
+In this example, `my-custom-install-script.sh` is a shell script at the root of the project.
+
+#### Overriding job definition
+
+If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare
+its definition after the template inclusion and specify any additional keys under it. For example:
+
+```yaml
+include:
+  template: License-Management.gitlab-ci.yml
+
+license_management:
+  stage: my-custom-stage
+```
+
+## Manual job definition
+
+CAUTION: **Caution:**
+The job definition shown below is supported on GitLab 11.5 and later versions _(although it's preferred to use 
+[the job definition template](#using-job-definition-template) since 11.9)_.
+It also requires the GitLab Runner 11.5 or later.
+For earlier versions, use the [previous job definitions](#previous-job-definitions).
+
+If you are using GitLab prior to 11.9, you can define it manually using the following snippet:
+
 ```yaml
 license_management:
   image:
     name: "registry.gitlab.com/gitlab-org/security-products/license-management:$CI_SERVER_VERSION_MAJOR-$CI_SERVER_VERSION_MINOR-stable"
     entrypoint: [""]
   stage: test
-  variables:
-    SETUP_CMD: ./my-custom-install-script.sh
   allow_failure: true
   script:
     - /run.sh analyze .
@@ -66,12 +103,23 @@ license_management:
       license_management: gl-license-management-report.json
 ```
 
-In this example, `my-custom-install-script.sh` is a shell script at the root of the project.
+Install custom project dependencies via `SETUP_CMD` variable:
 
-TIP: **Tip:**
-For [GitLab Ultimate][ee] users, this information will
-be automatically extracted and shown right in the merge request widget.
-[Learn more on License Management in merge requests](../../user/project/merge_requests/license_management.md).
+```yaml
+license_management:
+  image:
+    name: "registry.gitlab.com/gitlab-org/security-products/license-management:$CI_SERVER_VERSION_MAJOR-$CI_SERVER_VERSION_MINOR-stable"
+    entrypoint: [""]
+  stage: test
+  variables:
+    SETUP_CMD: ./my-custom-install-script.sh
+  allow_failure: true
+  script:
+    - /run.sh analyze .
+  artifacts:
+    reports:
+      license_management: gl-license-management-report.json
+```
 
 ## Previous job definitions
 
-- 
GitLab