Add an intro and an Overview section for Review Apps
[ci skip]
This commit is contained in:
Achilleas Pipinellis
parent
eee65421fe
commit
0881c3a82a
1 changed files with 84 additions and 44 deletions
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue