Documentation for Multi-Env feature flags

Also, add shared section about Environment scopes

Revise

Address feedback

fixed

Fix docs

Fix docs

Fix anchor

doc/ci/environments.md

@@ -598,6 +598,31 @@ fetch line:
 fetch = +refs/environments/*:refs/remotes/origin/environments/*
 ```
 
+## Environment specs (scopes) **[PREMIUM]**
+
+Some of EEP features can define a different behavior for each [Environments](#introduction-to-environments-and-deployments),
+for instance, [you can create a secret variable to be injected to production environment only](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 talk about scoping each environment group.
+
+Let's say there are three environments: `production`, `staging`, `review/feature-1` and `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,
+also use wildcard matching (`*`) for selecting a particular environment group,
+such as [Review apps](review_apps/index.md) (`review/*`).
+
+Please note that 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.
 
+Read more about [Environment scopes](../environments.md#environment-specs-scopes-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,41 @@ 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 scope.
 
 ![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).
+You may not want to enable a feature flag on production until QA team has
+confirmed that the feature is working correctly on the other testing environments.
+
+To define statuses 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#environment-specs-scopes-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#environment-specs-scopes-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 as well in order to quickly skim which flag is enabled on per environment.
+
 ## Integrating with your application
 
 In order to use Feature Flags, you need to first
@@ -71,9 +95,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 such. 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