Merge branch 'docs/refactor-review-apps-documentation' into 'master'

Add more introductory information to Review Apps page, and other refactoring.

Closes #50509

See merge request gitlab-org/gitlab-ce!21632
This commit is contained in:
Mike Lewis 2018-10-03 02:58:13 +00:00
commit 4fde49d255
3 changed files with 119 additions and 90 deletions

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 119 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 29 KiB

View file

@ -1,95 +1,94 @@
# Getting started with Review Apps # Review Apps
> - [Introduced][ce-21971] in GitLab 8.12. Further additions were made in GitLab > - [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.
> 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).
> - Inspired by [Heroku's Review Apps][heroku-apps] which itself was inspired by
> [Fourchette].
The basis of Review Apps is the [dynamic environments] which allow you to create 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).
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.
## Overview ## Overview
Simply put, a Review App is a mapping of a branch with an environment as there Review Apps are a collaboration tool that takes the hard work out of providing an environment to showcase product changes.
is a 1:1 relation between them.
Here's an example of what it looks like when viewing a merge request with a Review Apps:
dynamically set environment.
- 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) ![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 In this example, you can see a branch was:
built and deployed under a dynamic environment and can be previewed with an
also dynamically URL.
The details of the Review Apps implementation depend widely on your real - Successfully built.
technology stack and on your deployment process. The simplest case is to - Deployed under a dynamic environment that can be reached by clicking on the **View app** button.
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.
## Prerequisites ## How do Review Apps work?
To get a better understanding of Review Apps, you must first learn how 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.
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. 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.
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.
## Configuration ## Use cases
The configuration of Review apps depends on your technology stack and your Some supported use cases include the:
infrastructure. Read the [dynamic environments] documentation to understand
how to define and create them.
## 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` Review Apps usually make sense with web applications, but you can use them any way you'd like.
at a job level under the `environment` keyword.
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. Set up the infrastructure to host and deploy the Review Apps.
1. [Install][install-runner] and [configure][conf-runner] a Runner that does 1. [Install](https://docs.gitlab.com/runner/install/) and [configure](https://docs.gitlab.com/runner/commands/) a Runner to do deployment.
the 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. Set up a job in `.gitlab-ci.yml` that uses the predefined 1. Optionally, set a job that [manually stops](../environments.md#stopping-an-environment) the Review Apps.
[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.
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` 1. Push a branch and let the Runner deploy the Review App based on the `script` definition of the dynamic environment job.
definition of the dynamic environment job. 1. Wait for the Runner to build and deploy your web application.
1. Wait for the Runner to build and/or deploy your web app. 1. Click on the link that provided in the merge request related to the branch to see the changes live.
1. Click on the link that's present in the MR related to the branch and see the
changes live.
## Limitations ## Limitations
@ -97,27 +96,9 @@ Check the [environments limitations](../environments.md#limitations).
## Examples ## 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 - [NGINX](https://gitlab.com/gitlab-examples/review-apps-nginx).
to deploy a simple HTML website. - [OpenShift](https://gitlab.com/gitlab-examples/review-apps-openshift).
And below is a soon to be added examples list: See also the video [Demo: Cloud Native Development with GitLab](https://www.youtube.com/watch?v=jfIyQEwrocw), which includes a Review Apps example.
- 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