Added documentation about dynamic environments

CHANGELOG

@@ -25,6 +25,8 @@ v 8.12.0 (unreleased)
   - Fix sorting of issues in API
   - Sort project variables by key. !6275 (Diego Souza)
   - Ensure specs on sorting of issues in API are deterministic on MySQL
+  - Added ability to use predefined CI variables for environment name
+  - Added ability to specify URL in environment configuration in gitlab-ci.yml
   - Escape search term before passing it to Regexp.new !6241 (winniehell)
   - Fix pinned sidebar behavior in smaller viewports !6169
   - Fix file permissions change when updating a file on the Gitlab UI !5979

doc/ci/yaml/README.md

@@ -553,7 +553,7 @@ GitLab.
 If `environment` is specified and no environment under that name exists, a new
 one will be created automatically.
 
-The `environment` name must contain only letters, digits, '-' and '_'. Common
+The `environment` name must be a valid git reference name. Common
 names are `qa`, `staging`, and `production`, but you can use whatever name works
 with your workflow.
 
@@ -571,6 +571,33 @@ deploy to production:
 The `deploy to production` job will be marked as doing deployment to
 `production` environment.
 
+#### dynamic environments
+
+>**Note:**
+Introduced in GitLab 8.12.
+
+`environment` can also represent a configuration hash with `name` and `url`.
+These parameters can use any of defined CI variables (including predefined, secure variables and .gitlab-ci.yml variables).
+
+The common use case is to create a dynamic environments for branches and use them as review apps.
+
+---
+
+**Example configurations**
+
+```
+deploy as review app:
+  stage: deploy
+  script: ...
+  environment: 
+    name: review-apps/$CI_BUILD_REF_NAME
+    url: https://$CI_BUILD_REF_NAME.review.example.com/
+```
+
+The `deploy to production` job will be marked as doing deployment to
+`production` environment.
+
+
 ### artifacts
 
 >**Notes:**