Merge branch 'docs-multiple-environment-feature-flags' into 'master'

Documentation for Multi-Env feature flags

Closes #8621

See merge request gitlab-org/gitlab-ee!9385

doc/ci/environments.md

@@ -598,6 +598,38 @@ fetch line:
 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](#introduction-to-environments-and-deployments).
+For example, you can [create a secret variable to be injected only into a production environment](variables/README.md#limiting-environment-scopes-of-variables-premium).
+In most cases, these features use the _environment specs_ mechanism, which offers
+an efficient way to implement scoping within each environment group.
+
+Let's say there are four environments:
+
+- `production`
+- `staging`
+- `review/feature-1`
+- `review/feature-2`
+
+Each environment can be matched with the following environment spec:
+
+| Environment Spec  | `production` | `staging` | `review/feature-1` | `review/feature-2` |
+| ----------------  | ----------   | -------   | ----------------   | ----------------   |
+|  *                | Matched      | Matched   | Matched            | Matched            |
+|  production       | Matched      |           |                    |                    |
+|  staging          |              | Matched   |                    |                    |
+|  review/*         |              |           | Matched            | Matched            |
+|  review/feature-1 |              |           | Matched            |                    |
+
+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/*`).
+
+NOTE: **Note:**
+The most _specific_ spec takes precedence over the other wildcard matching.
+In this case, `review/feature-1` spec takes precedence over `review/*` and `*` specs.
+
 ## Limitations
 
 1. You are limited to use only the [CI predefined variables][variables] in the

doc/ci/variables/README.md

@@ -265,6 +265,8 @@ 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).
+
 ### Manually-specified variables
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/44059) in GitLab 10.8.

doc/user/project/operations/feature_flags.md

@@ -46,17 +46,45 @@ To add a new feature flag:
     or an underscore (`_`).
 
 1. Give it a description (optional, 255 characters max).
-1. If you want to activate it, click on the "Active" checkbox.
+1. Define environment [specs](#define-environment-specs). If you want the flag on by default, enable the catch-all [wildcard spec (`*`)](#define-environment-specs)
 1. Click **Create feature flag**.
 
 Once a feature flag is created, the list of existing feature flags will be presented
 with ability to edit or remove them.
 
 To make a feature flag active or inactive, click the pencil icon to edit it,
-and toggle the "Active" checkbox.
+and toggle the status for each [spec](#define-environment-specs).
 
 ![Feature flags list](img/feature_flags_list.png)
 
+## Define environment specs
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8621) in GitLab 11.8.
+
+In general, an application is deployed to multiple environments, such as
+production, staging and [review apps](../../../ci/review_apps/index.md).
+For example, you may not want to enable a feature flag on production until your QA team has
+first confirmed that the feature is working correctly on testing environments.
+
+To handle these situations, you can enable a feature flag on a particular environment
+with [Environment specs](../../../ci/environments.md#scoping-environments-with-specs-premium).
+You can define multiple specs per flag so that you can control your feature flag more granularly.
+
+To define specs for each environment:
+
+1. Navigate to your project's **Operations > Feature Flags**.
+1. Click on the **New Feature Flag** button or edit an existing flag.
+1. Set the status of the default [spec](../../../ci/environments.md#scoping-environments-with-specs-premium) (`*`). This status will be used for _all_ environments.
+1. If you want to enable/disable the feature on a specific environment, create a new [spec](../../../ci/environments.md#scoping-environments-with-specs-premium) and type the environment name.
+1. Set the status of the additional spec. This status takes precedence over the default spec's status since we always use the most specific match available.
+1. Click **Create feature flag** or **Update feature flag**.
+
+![Feature flag specs list](img/specs_list.png)
+
+NOTE: **NOTE**
+We'd highly recommend you to use the [Environment](../../../ci/environments.md)
+feature in order to quickly assess which flag is enabled per environment.
+
 ## Integrating with your application
 
 In order to use Feature Flags, you need to first
@@ -71,9 +99,10 @@ To get the access credentials that your application will need to talk to GitLab:
 1. Click on the **Configure** button to see the values:
     - **API URL**: URL where the client (application) connects to get a list of feature flags.
     - **Instance ID**: Unique token that authorizes the retrieval of the feature flags.
-    - **Application name**: The name of the running environment. By default this is
-      set to `production`, but you can use whatever you want in your application
-      (e.g.,`staging`, `review/feature`).
+    - **Application name**: The name of the running environment. For instance,
+       if the application runs for production server, application name would be
+      `production` or similar. This value is used for
+      [the environment spec evaluation](#define-environment-specs).
 
 NOTE: **Note:**
 The meaning of these fields might change over time. For example, we are not sure