Add an intro and an Overview section for Review Apps

[ci skip]

1 files changed, 83 insertions, 43 deletions

diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md
index ee279025a9d..ce1fbaaab04 100644
--- a/doc/ci/review_apps/index.md
+++ b/doc/ci/review_apps/index.md
@@ -1,29 +1,87 @@
-# Review apps
+# Getting started with Review Apps
 
 > [Introduced][ce-21971] in GitLab 8.12. Further additions were made in GitLab 8.13.
+>
+Inspired by [Heroku's Review Apps][heroku-apps] which itself was inspired by
+[Fourchette].
 
-Review apps are automatically-created [environments] that run your code for each
-branch. That means [merge requests] can be reviewed in a live-running environment.
+The base of Review Apps is the [dynamic environments] which allow you to create
+a new environment (dynamically) for each one of your branches.
 
-They mostly make sense to be used with web applications.
+A Review App can then be visible as a link when you visit the [merge request]
+relevant to the branch. That way, you are able to see live all changes introduced
+by the merge request changes. Reviewing anything, from performance to interface
+changes, becomes much easier with a live environment and as such, Review Apps
+can make a huge impact on your development flow.
 
-Review Apps can make a huge impact on your development flow. Reviewing anything
-from performance to interface changes becomes much easier with a live environment.
+They mostly make sense to be used with web applications, but you can use them
+any way you'd like.
 
->
-Inspired by [Heroku's Review Apps][heroku-apps] which itself was inspired by
-[Fourchette].
+## Overview
+
+Simply put, a Review App is a mapping of
+a branch with an environment as there is a 1:1 relation between them.
+
+To get a better understanding of Review Apps, you must first learn how
+environments and deployments work. The following docs will help you grasp that
+knowledge:
+
+1. First, learn about [environments][] and their role in the development workflow.
+1. Then make a small stop to learn about [CI variables][variables] and how they
+   can be used in your CI jobs.
+1. Next, explore the [`environment` syntax][yaml-env] as defined in `.gitlab-ci.yml`.
+   This will be your primary reference when you are finally comfortable with
+   how environments work.
+1. Additionally, find out about [manual actions][] and how you can use them to
+   deploy to critical environments like production with the push of a button.
+1. And as a last step, follow the [NGINX example tutorial][app-nginx] which will
+   guide you step by step to set up the infrastructure and make use of
+   Review Apps with a simple HTML site and NGINX.
+
+## Configuration
+
+For configuration examples see the [dynamic environments] documentation.
+
+## Creating and destroying Review Apps
+
+The creation and destruction of a Review App is defined in `.gitlab-ci.yml`.
+Check the [environments] documentation how to do so.
+
+## A simple workflow
+
+The process of adding Review Apps in your workflow would look like:
+
+1. Set up the infrastructure to host and deploy the Review Apps.
+1. Install and configure a Runner that does the deployment.
+1. Set up a job in `.gitlab-ci.yml` that uses the predefined
+   [predefined CI environment variable][variables] `${CI_BUILD_REF_NAME}` to
+   create dynamic environments and restrict it to run only on branches.
+1. Optionally set a job that stops the Review Apps.
+
+From there on, you would follow the branched Git flow:
+
+1. Push a branch and let the Runner deploy the Review App based on the `script`
+   definition of the dynamic environment job.
+1. Wait for the Runner to build and/or deploy your web app.
+1. Click on the link that's present in the MR related to the branch and see the
+   changes live.
+
+### Limitations
+
+We are limited to use only [CI predefined variables][variables].
 
-## Dynamic environments
+## Examples
+
+A list of examples used with Review Apps can be found below:
 
-You can now use predefined CI variables as a name for environments. In addition,
-you can specify a URL for the environment configuration in your .gitlab-ci.yml
-file.
+- [Use with NGINX][app-nginx] - Use NGINX and the shell executor of GitLab Runner
+  to deploy a simple HTML website.
 
-- Mapping branch with environment
+And below is a soon to be added examples list:
 
-This issue describes dynamic environments implementation, mostly to be used with dynamically create applications.
-These application will be mostly used for Review Apps.
+- Use with Amazon S3
+- Use on Heroku with dpl
+- Use with OpenShift/kubernetes
 
 ## Assumptions
 
@@ -34,23 +92,10 @@ These application will be mostly used for Review Apps.
 1. We need some form to distinguish between production/staging and review app environment,
 1. We don't try to manage life cycle of deployments in the first iteration, possibly we will extend a Pipeline to add jobs that will be responsible either for cleaning up or removing old deployments and closing environments.
 
-## Configuration
-
-```
-review_apps:
-  environment:
-    name: review/$CI_BUILD_REF_NAME
-    url: http://$CI_BUILD_REF_NAME.review.gitlab.com/
-```
-
-### Remarks
-
-1. We are limited to use only CI predefined variables, since this is not easy task to pass the URL from build,
-2. I do prefer nested `url:` since this allows us in the future to extend that with more `environment:` configuration or constraints, like: `required_variables:` or `access_level` of user allowed to use that.
-3. Following the problem from (1) we can extend `url:` with a `regexp` that will be used to fish a URL from build log.
-
 ## Distinguish between production and review apps
 
+- Are dynamic environments distinguishable by the slash in `environment:url`?
+
 ### Convention over configuration
 
 We would expect the environments to be of `type/name`:
@@ -65,18 +110,13 @@ The `type/name` also plays nice with `Variables` and `Runners`, because we can l
 1. We could extend the resources with a field that would allow us to filter for what types it can be used, ex.: `production/*` or `review-apps/*`
 2. We could limit runners to be used only by `review-apps/*`,
 
-## Destroying Review Apps
-
-
-## Examples
-
-- Use with NGINX
-- Use with Amazon S3
-- Use on Heroku with dpl
-- Use with OpenShift/kubernetes
-
+[app-nginx]: nginx_guide.md
 [ce-21971]: https://gitlab.com/gitlab-org/gitlab-ce/issues/21971
-[heroku-apps]: https://devcenter.heroku.com/articles/github-integration-review-apps
+[dynamic environments]: ../environments.md#dynamic-environments
 [environments]: ../environments.md
-[merge requests]: ../../user/project/merge_requests.md
 [fourchette]: https://github.com/rainforestapp/fourchette
+[heroku-apps]: https://devcenter.heroku.com/articles/github-integration-review-apps
+[manual actions]: ../environments.md#manual-actions
+[merge request]: ../../user/project/merge_requests.md
+[variables]: ../variables/README.md
+[yaml-env]: ../yaml/README.md#environment