diff --git a/doc/ci/review_apps/img/continuous-delivery-review-apps.svg b/doc/ci/review_apps/img/continuous-delivery-review-apps.svg new file mode 100644 index 00000000000..90ac763a01e --- /dev/null +++ b/doc/ci/review_apps/img/continuous-delivery-review-apps.svg @@ -0,0 +1,48 @@ + + + + review-apps-CD-outlined + Created with Sketch. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/doc/ci/review_apps/img/review_apps_preview_in_mr.png b/doc/ci/review_apps/img/review_apps_preview_in_mr.png index 7d0923f198f..3e6506a6a3a 100644 Binary files a/doc/ci/review_apps/img/review_apps_preview_in_mr.png and b/doc/ci/review_apps/img/review_apps_preview_in_mr.png differ diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 1b17f6ac5ea..64be011008e 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -1,95 +1,94 @@ -# Getting started with Review Apps +# Review Apps -> - [Introduced][ce-21971] in GitLab 8.12. Further additions were made in GitLab -> 8.13 and 8.14. -> - Inspired by [Heroku's Review Apps][heroku-apps] which itself was inspired by -> [Fourchette]. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/21971) in GitLab 8.12. Further additions were made in GitLab 8.13 and 8.14. +> - Inspired by [Heroku's Review Apps](https://devcenter.heroku.com/articles/github-integration-review-apps), which itself was inspired by [Fourchette](https://github.com/rainforestapp/fourchette). -The basis of Review Apps is the [dynamic environments] which allow you to create -a new environment (dynamically) for each one of your branches. - -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. - -They mostly make sense to be used with web applications, but you can use them -any way you'd like. +For a video introduction to Review Apps, see [8.14 Webcast: Review Apps & Time Tracking Beta (EE) - GitLab Release](https://www.youtube.com/watch?v=CteZol_7pxo). ## Overview -Simply put, a Review App is a mapping of a branch with an environment as there -is a 1:1 relation between them. +Review Apps are a collaboration tool that takes the hard work out of providing an environment to showcase product changes. -Here's an example of what it looks like when viewing a merge request with a -dynamically set environment. +Review Apps: + +- Provide an automatic live preview of changes made in a feature branch by spinning up a dynamic environment for your merge requests. +- Allow designers and product manages to see your changes without needing to check out your branch and run your changes in a sandbox environment. +- Are fully integrated with the [GitLab DevOps LifeCycle](../../README.md#complete-devops-with-gitlab). +- Allow you to deploy your changes wherever you want. + +![Review Apps Workflow](img/continuous-delivery-review-apps.svg) + +Reviewing anything, from performance to interface changes, becomes much easier with a live environment and so Review Apps can make a large impact on your development flow. + +## What are Review Apps? + +A Review App is a mapping of a branch with an [environment](../environments.md). The following is an example of a merge request with an environment set dynamically. ![Review App in merge request](img/review_apps_preview_in_mr.png) -In the image above you can see that the `add-new-line` branch was successfully -built and deployed under a dynamic environment and can be previewed with an -also dynamically URL. +In this example, you can see a branch was: -The details of the Review Apps implementation depend widely on your real -technology stack and on your deployment process. The simplest case is to -deploy a simple static HTML website, but it will not be that straightforward -when your app is using a database for example. To make a branch be deployed -on a temporary instance and booting up this instance with all required software -and services automatically on the fly is not a trivial task. However, it is -doable, especially if you use Docker, or at least a configuration management -tool like Chef, Puppet, Ansible or Salt. +- Successfully built. +- Deployed under a dynamic environment that can be reached by clicking on the **View app** button. -## Prerequisites +## How do Review Apps work? -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: +The basis of Review Apps in GitLab is [dynamic environments](../environments.md#dynamic-environments), which allow you to dynamically create a new environment for each branch. -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 [example tutorials](#examples) which will - guide you step by step to set up the infrastructure and make use of - Review Apps. +Access to the Review App is made available as a link on the [merge request](../../user/project/merge_requests.md) relevant to the branch. Review Apps enable you to review all changes proposed by the merge request in live environment. -## Configuration +## Use cases -The configuration of Review apps depends on your technology stack and your -infrastructure. Read the [dynamic environments] documentation to understand -how to define and create them. +Some supported use cases include the: -## Creating and destroying Review Apps +- Simple case of deploying a simple static HTML website. +- More complicated case of an application that uses a database. Deploying a branch on a temporary instance and booting up this instance with all required software and services automatically on the fly is not a trivial task. However, it is possible, especially if you use Docker or a configuration management tool like Chef, Puppet, Ansible, or Salt. -The creation and destruction of a Review App is defined in `.gitlab-ci.yml` -at a job level under the `environment` keyword. +Review Apps usually make sense with web applications, but you can use them any way you'd like. -Check the [environments] documentation how to do so. +## Implementing Review Apps -## A simple workflow +Implementing Review Apps depends on your: -The process of adding Review Apps in your workflow would look like: +- Technology stack. +- Deployment process. + +### Prerequisite Knowledge + +To get a better understanding of Review Apps, review documentation on how environments and deployments work. Before you implement your own Review Apps: + +1. Learn about [environments](../environments.md) and their role in the development workflow. +1. Learn about [CI variables](../variables/README.md) and how they can be used in your CI jobs. +1. Explore the [`environment` syntax](../yaml/README.md#environment) as defined in `.gitlab-ci.yml`. This will become a primary reference. +1. Additionally, find out about [manual actions](../environments.md#manual-actions) and how you can use them to deploy to critical environments like production with the push of a button. +1. Follow the [example tutorials](#examples). These will guide you through setting up infrastructure and using Review Apps. + +### Configuring dynamic environments + +Configuring Review Apps dynamic environments depends on your technology stack and infrastructure. + +For more information, see [dynamic environments](../environments.md#dynamic-environments) documentation to understand how to define and create them. + +### Creating and destroying Review Apps + +Creating and destroying Review Apps is defined in `.gitlab-ci.yml` at a job level under the `environment` keyword. + +For more information, see [Introduction to environments and deployments](../environments.md). + +### Adding Review Apps to your workflow + +The process of adding Review Apps in your workflow is as follows: 1. Set up the infrastructure to host and deploy the Review Apps. -1. [Install][install-runner] and [configure][conf-runner] 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_COMMIT_REF_NAME}` to - create dynamic environments and restrict it to run only on branches. -1. Optionally set a job that [manually stops][manual-env] the Review Apps. +1. [Install](https://docs.gitlab.com/runner/install/) and [configure](https://docs.gitlab.com/runner/commands/) a Runner to do deployment. +1. Set up a job in `.gitlab-ci.yml` that uses the predefined [predefined CI environment variable](../variables/README.md) `${CI_COMMIT_REF_NAME}` to create dynamic environments and restrict it to run only on branches. +1. Optionally, set a job that [manually stops](../environments.md#stopping-an-environment) the Review Apps. -From there on, you would follow the branched Git flow: +After adding Review Apps to your workflow, you follow the branched Git flow. That is: -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. +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 deploy your web application. +1. Click on the link that provided in the merge request related to the branch to see the changes live. ## Limitations @@ -97,27 +96,9 @@ Check the [environments limitations](../environments.md#limitations). ## Examples -A list of examples used with Review Apps can be found below: +The following are example projects that use Review Apps with: -- [Use with NGINX][app-nginx] - Use NGINX and the shell executor of GitLab Runner - to deploy a simple HTML website. +- [NGINX](https://gitlab.com/gitlab-examples/review-apps-nginx). +- [OpenShift](https://gitlab.com/gitlab-examples/review-apps-openshift). -And below is a soon to be added examples list: - -- Use with Amazon S3 -- Use on Heroku with dpl -- Use with OpenShift/kubernetes - -[app-nginx]: https://gitlab.com/gitlab-examples/review-apps-nginx -[ce-21971]: https://gitlab.com/gitlab-org/gitlab-ce/issues/21971 -[dynamic environments]: ../environments.md#dynamic-environments -[environments]: ../environments.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 -[install-runner]: https://docs.gitlab.com/runner/install/ -[conf-runner]: https://docs.gitlab.com/runner/commands/ -[manual-env]: ../environments.md#stopping-an-environment +See also the video [Demo: Cloud Native Development with GitLab](https://www.youtube.com/watch?v=jfIyQEwrocw), which includes a Review Apps example.