Merge branch 'docs-ssot-ci-variables' into 'master'

Docs: ssot - ci variables

See merge request gitlab-org/gitlab-ce!28606

8 files changed, 69 insertions, 17 deletions

diff --git a/doc/ci/README.md b/doc/ci/README.md
index 27bde2ac0f1..93b82a065b3 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -1,6 +1,7 @@
 ---
 comments: false
 description: "Learn how to use GitLab CI/CD, the GitLab built-in Continuous Integration, Continuous Deployment, and Continuous Delivery toolset to build, test, and deploy your application."
+type: index
 ---
 
 # GitLab CI/CD
diff --git a/doc/ci/environments.md b/doc/ci/environments.md
index 5a14ac17aec..9f930833093 100644
--- a/doc/ci/environments.md
+++ b/doc/ci/environments.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Environments and deployments
 
 > Introduced in GitLab 8.9.
@@ -667,9 +671,24 @@ fetch = +refs/environments/*:refs/remotes/origin/environments/*
 
 ### Scoping environments with specs **[PREMIUM]**
 
-Some GitLab [Enterprise Edition](https://about.gitlab.com/pricing/) features can
-behave differently for each environment. For example, you can
-[create a secret variable to be injected only into a production environment](variables/README.md#limiting-environment-scopes-of-environment-variables-premium).
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2112) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.4.
+
+You can limit the environment scope of a variable by
+defining which environments it can be available for.
+
+Wildcards can be used, and the default environment scope is `*`, which means
+any jobs will have this variable, not matter if an environment is defined or
+not.
+
+For example, if the environment scope is `production`, then only the jobs
+having the environment `production` defined would have this specific variable.
+Wildcards (`*`) can be used along with the environment name, therefore if the
+environment scope is `review/*` then any jobs with environment names starting
+with `review/` would have that particular variable.
+
+Some GitLab features can behave differently for each environment.
+For example, you can
+[create a secret variable to be injected only into a production environment](variables/README.md#limiting-environment-scopes-of-environment-variables-premium). **[PREMIUM]**
 
 In most cases, these features use the _environment specs_ mechanism, which offers
 an efficient way to implement scoping within each environment group.
@@ -693,7 +712,7 @@ Each environment can be matched with the following environment spec:
 
 As you can see, you can use specific matching for selecting a particular environment,
 and also use wildcard matching (`*`) for selecting a particular environment group,
-such as [Review apps](review_apps/index.md) (`review/*`).
+such as [Review Apps](review_apps/index.md) (`review/*`).
 
 NOTE: **Note:**
 The most _specific_ spec takes precedence over the other wildcard matching.
@@ -712,3 +731,15 @@ Below are some links you may find interesting:
 - [A blog post on Deployments & Environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/)
 - [Review Apps - Use dynamic environments to deploy your code for every branch](review_apps/index.md)
 - [Deploy Boards for your applications running on Kubernetes](https://docs.gitlab.com/ee/user/project/deploy_boards.html) **[PREMIUM]**
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md
index 0045fa2fb1f..bd2b9b099f2 100644
--- a/doc/ci/introduction/index.md
+++ b/doc/ci/introduction/index.md
@@ -1,5 +1,6 @@
 ---
 description: "An overview of Continuous Integration, Continuous Delivery, and Continuous Deployment, as well as an introduction to GitLab CI/CD."
+type: concepts
 ---
 
 # Introduction to CI/CD with GitLab
diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md
index 2157a6dc097..43fc3a1ad47 100644
--- a/doc/ci/variables/README.md
+++ b/doc/ci/variables/README.md
@@ -1,5 +1,6 @@
 ---
 table_display_block: true
+type: reference
 ---
 
 # GitLab CI/CD environment variables
@@ -388,21 +389,9 @@ Once you set them, they will be available for all subsequent pipelines.
 
 ### Limiting environment scopes of environment variables **[PREMIUM]**
 
-> [Introduced][ee-2112] in [GitLab Premium](https://about.gitlab.com/pricing/) 9.4.
-
 You can limit the environment scope of a variable by
 [defining which environments][envs] it can be available for.
 
-Wildcards can be used, and the default environment scope is `*` which means
-any jobs will have this variable, not matter if an environment is defined or
-not.
-
-For example, if the environment scope is `production`, then only the jobs
-having the environment `production` defined would have this specific variable.
-Wildcards (`*`) can be used along with the environment name, therefore if the
-environment scope is `review/*` then any jobs with environment names starting
-with `review/` would have that particular variable.
-
 To learn more about about scoping environments, see [Scoping environments with specs](../environments.md#scoping-environments-with-specs-premium).
 
 ### Deployment environment variables
@@ -716,7 +705,6 @@ MIIFQzCCBCugAwIBAgIRAL/ElDjuf15xwja1ZnCocWAwDQYJKoZIhvcNAQELBQAw'
 ...
 ```
 
-[ee-2112]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2112
 [ce-13784]: https://gitlab.com/gitlab-org/gitlab-ce/issues/13784 "Simple protection of CI variables"
 [envs]: ../environments.md
 [protected branches]: ../../user/project/protected_branches.md
diff --git a/doc/ci/variables/deprecated_variables.md b/doc/ci/variables/deprecated_variables.md
index 2642c9b0eb4..cdca5bf27fc 100644
--- a/doc/ci/variables/deprecated_variables.md
+++ b/doc/ci/variables/deprecated_variables.md
@@ -1,5 +1,12 @@
+---
+type: reference
+---
+
 # Deprecated GitLab CI/CD variables
 
+Read through this document to learn what predefined variables
+were deprecated and their new references.
+
 ## GitLab 9.0 renamed variables
 
 To follow conventions of naming across GitLab, and to further move away from the
diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md
index 4e902c042e6..4655eec51de 100644
--- a/doc/ci/variables/predefined_variables.md
+++ b/doc/ci/variables/predefined_variables.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Predefined environment variables reference
 
 For an introduction on this subject, read through the
diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md
index 0470cf52654..8009b1d5e8a 100644
--- a/doc/ci/variables/where_variables_can_be_used.md
+++ b/doc/ci/variables/where_variables_can_be_used.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Where variables can be used
 
 As it's described in the [CI/CD variables](README.md) docs, you can
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 3731585b4e5..716363a8d6d 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # GitLab CI/CD Pipeline Configuration Reference
 
 GitLab CI/CD [pipelines](../pipelines.md) are configured using a YAML file called `.gitlab-ci.yml` within each project.
@@ -2787,6 +2791,18 @@ using Git 2.10 or newer:
 git push -o ci.skip
 ```
 
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
+
 [ce-6323]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6323
 [ce-6669]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6669
 [ce-7983]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7983