From 4a5c21728ee4e6c3ef8e1c410ee0f0c9a47634cc Mon Sep 17 00:00:00 2001
From: Kamil Trzcinski <ayufan@ayufan.eu>
Date: Wed, 14 Sep 2016 23:33:10 +0200
Subject: [PATCH] Added documentation about dynamic environments

---
 CHANGELOG             |  2 ++
 doc/ci/yaml/README.md | 29 ++++++++++++++++++++++++++++-
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG b/CHANGELOG
index e9445a18a18..3da548ef2af 100644
--- a/CHANGELOG
+++ b/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
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index ff4c8ddc54b..4772565fac9 100644
--- a/doc/ci/yaml/README.md
+++ b/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:**