9 files changed, 84 insertions, 20 deletions
diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md
index 3f72fe3e9eb..d703e106e76 100644
--- a/doc/ci/caching/index.md
+++ b/doc/ci/caching/index.md
@@ -100,7 +100,7 @@ From the perspective of the Runner, in order for cache to work effectively, one
 of the following must be true:
 
 - Use a single Runner for all your jobs.
-- Use multiple Runners (in autoscale mode or not) that use.
+- Use multiple Runners (in autoscale mode or not) that use
   [distributed caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching),
   where the cache is stored in S3 buckets (like shared Runners on GitLab.com).
 - Use multiple Runners (not in autoscale mode) of the same architecture that
diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md
index 5222cc45bc4..dd112dadc40 100644
--- a/doc/ci/docker/using_docker_build.md
+++ b/doc/ci/docker/using_docker_build.md
@@ -142,9 +142,12 @@ In order to do that, follow the steps:
       # The 'docker' hostname is the alias of the service container as described at
       # https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services
       #
-      # Note that if you're using Kubernetes executor, the variable should be set to
-      # tcp://localhost:2375 because of how Kubernetes executor connects services
+      # Note that if you're using the Kubernetes executor, the variable should be set to
+      # tcp://localhost:2375/ because of how the Kubernetes executor connects services
       # to the job container
+      # DOCKER_HOST: tcp://localhost:2375/
+      #
+      # For non-Kubernetes executors, we use tcp://docker:2375/
       DOCKER_HOST: tcp://docker:2375/
       # When using dind, it's wise to use the overlayfs driver for
       # improved performance.
diff --git a/doc/ci/multi_project_pipelines.md b/doc/ci/multi_project_pipelines.md
index 17d5599e40a..bcd92243d97 100644
--- a/doc/ci/multi_project_pipelines.md
+++ b/doc/ci/multi_project_pipelines.md
@@ -138,6 +138,34 @@ staging:
 The `ENVIRONMENT` variable will be passed to every job defined in a downstream
 pipeline. It will be available as an environment variable when GitLab Runner picks a job.
 
+In the following configuration, the `MY_VARIABLE` variable will be passed
+downstream, because jobs inherit variables declared in top-level `variables`:
+
+```yaml
+variables:
+  MY_VARIABLE: my-value
+
+my-pipeline:
+  variables:
+    ENVIRONMENT: something
+  trigger: my/project
+```
+
+You might want to pass some information about the upstream pipeline using, for
+example, predefined variables. In order to do that, you can use interpolation
+to pass any variable. For example:
+
+```yaml
+my-pipeline:
+  variables:
+    UPSTREAM_BRANCH: $CI_COMMIT_REF_NAME
+  trigger: my/project
+```
+
+In this scenario, the `UPSTREAM_BRANCH` variable with a value related to the
+upstream pipeline will be passed to a `downstream` job, and will be available
+within the context of all downstream builds.
+
 ### Limitations
 
 Because bridge jobs are a little different to regular jobs, it is not
diff --git a/doc/ci/services/README.md b/doc/ci/services/README.md
index 2eda5d23976..7fe12eb53e7 100644
--- a/doc/ci/services/README.md
+++ b/doc/ci/services/README.md
@@ -1,13 +1,18 @@
 ---
 comments: false
+type: index
 ---
 
-# GitLab CI Services
+# GitLab CI services examples
 
-GitLab CI uses the `services` keyword to define what docker containers should
-be linked with your base image. Below is a list of examples you may use.
+The [`services`](../docker/using_docker_images.md#what-is-a-service)
+keyword defines a Docker image that runs during a `job` linked to the
+Docker image that the image keyword defines. This allows you to access
+the service image during build time.
+
+The service image can run any application, but the most common use
+case is to run a database container, for example:
 
 - [Using MySQL](mysql.md)
 - [Using PostgreSQL](postgres.md)
 - [Using Redis](redis.md)
-- [Using Other Services](../docker/using_docker_images.md#what-is-a-service)
diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md
index 5fa378fc4c2..697452cee83 100644
--- a/doc/ci/services/mysql.md
+++ b/doc/ci/services/mysql.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Using MySQL
 
 As many applications depend on MySQL as their database, you will eventually
diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md
index 2e6d7ae94d2..211eea26eb0 100644
--- a/doc/ci/services/postgres.md
+++ b/doc/ci/services/postgres.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Using PostgreSQL
 
 As many applications depend on PostgreSQL as their database, you will
diff --git a/doc/ci/services/redis.md b/doc/ci/services/redis.md
index 36f71427ae7..8b227154b06 100644
--- a/doc/ci/services/redis.md
+++ b/doc/ci/services/redis.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Using Redis
 
 As many applications depend on Redis as their key-value store, you will
diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md
index 67e1d316f02..2157a6dc097 100644
--- a/doc/ci/variables/README.md
+++ b/doc/ci/variables/README.md
@@ -91,10 +91,9 @@ This means that the value of the variable will be hidden in job logs,
 though it must match certain requirements to do so:
 
 - The value must be in a single line.
-- The value must not have escape characters.
-- The value must not use variables.
-- The value must not have any whitespace.
+- The value must contain only letters, numbers, or underscores.
 - The value must be at least 8 characters long.
+- The value must not use variables.
 
 If the value does not meet the requirements above, then the CI variable will fail to save.
 In order to save, either alter the value to meet the masking requirements
@@ -612,8 +611,8 @@ $'\''git'\'' "checkout" "-f" "-q" "dd648b2e48ce6518303b0bb580b2ee32fadaf045"
 Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-machine-1480971377-317a7d0f-digital-ocean-4gb...
 ++ export CI=true
 ++ CI=true
-++ export CI_API_V4_API_URL=https://example.com:3000/api/v4
-++ CI_API_V4_API_URL=https://example.com:3000/api/v4
+++ export CI_API_V4_URL=https://example.com:3000/api/v4
+++ CI_API_V4_URL=https://example.com:3000/api/v4
 ++ export CI_DEBUG_TRACE=false
 ++ CI_DEBUG_TRACE=false
 ++ export CI_COMMIT_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045
@@ -652,8 +651,8 @@ Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-mach
 ++ GITLAB_CI=true
 ++ export CI=true
 ++ CI=true
-++ export CI_API_V4_API_URL=https://example.com:3000/api/v4
-++ CI_API_V4_API_URL=https://example.com:3000/api/v4
+++ export CI_API_V4_URL=https://example.com:3000/api/v4
+++ CI_API_V4_URL=https://example.com:3000/api/v4
 ++ export GITLAB_CI=true
 ++ GITLAB_CI=true
 ++ export CI_JOB_ID=7046507
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 8667eacd3d5..18c85618b1b 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -386,17 +386,12 @@ job:
     - branches@gitlab-org/gitlab-ce
   except:
     - master@gitlab-org/gitlab-ce
-    - release/.*@gitlab-org/gitlab-ce
+    - /^release/.*$/@gitlab-org/gitlab-ce
 ```
 
 The above example will run `job` for all branches on `gitlab-org/gitlab-ce`,
 except `master` and those with names prefixed with `release/`.
 
-NOTE: **Note:**
-Because `@` is used to denote the beginning of a ref's repository path,
-matching a ref name containing the `@` character in a regular expression
-requires the use of the hex character code match `\x40`.
-
 If a job does not have an `only` rule, `only: ['branches', 'tags']` is set by
 default. If it doesn't have an `except` rule, it is empty.
 
@@ -415,6 +410,28 @@ job:
   only: ['branches', 'tags']
 ```
 
+#### Regular expressions
+
+Because `@` is used to denote the beginning of a ref's repository path,
+matching a ref name containing the `@` character in a regular expression
+requires the use of the hex character code match `\x40`.
+
+Only the tag or branch name can be matched by a regular expression.
+The repository path, if given, is always matched literally.
+
+If a regular expression shall be used to match the tag or branch name,
+the entire ref name part of the pattern has to be a regular expression,
+and must be surrounded by `/`.
+(With regular expression flags appended after the closing `/`.)
+So `issue-/.*/` won't work to match all tag names or branch names
+that begin with `issue-`.
+
+TIP: **Tip**
+Use anchors `^` and `$` to avoid the regular expression
+matching only a substring of the tag name or branch name.
+For example, `/^issue-.*$/` is equivalent to `/^issue-/`,
+while just `/issue/` would also match a branch called `severe-issues`.
+
 ### Supported `only`/`except` regexp syntax
 
 CAUTION: **Warning:**