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. - -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. - -They mostly make sense to be used with web applications. - -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. - > Inspired by [Heroku's Review Apps][heroku-apps] which itself was inspired by [Fourchette]. -## Dynamic environments +The base of Review Apps is the [dynamic environments] which allow you to create +a new environment (dynamically) for each one of your branches. -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. +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. -- Mapping branch with environment +They mostly make sense to be used with web applications, but you can use them +any way you'd like. -This issue describes dynamic environments implementation, mostly to be used with dynamically create applications. -These application will be mostly used for Review Apps. +## 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]. + +## Examples + +A list of examples used with Review Apps can be found below: + +- [Use with NGINX][app-nginx] - Use NGINX and the shell executor of GitLab Runner + to deploy a simple HTML website. + +And below is a soon to be added examples list: + +- 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