debian-mirror-gitlab/doc/ci/review_apps/index.md

323 lines
15 KiB
Markdown
Raw Normal View History

2019-09-04 21:01:54 +05:30
---
2020-05-24 23:13:21 +05:30
stage: Release
group: Progressive Delivery
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
2019-09-04 21:01:54 +05:30
type: reference
---
2018-12-05 23:21:45 +05:30
# Review Apps
2017-08-17 22:00:37 +05:30
2020-06-23 00:09:42 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21971) in GitLab 8.12. Further additions were made in GitLab 8.13 and 8.14.
2018-12-05 23:21:45 +05:30
> - 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).
2017-08-17 22:00:37 +05:30
2019-09-04 21:01:54 +05:30
Review Apps is a collaboration tool that takes the hard work out of providing an environment to showcase product changes.
2017-08-17 22:00:37 +05:30
2019-07-31 22:56:46 +05:30
## Introduction
2018-12-05 23:21:45 +05:30
Review Apps:
- Provide an automatic live preview of changes made in a feature branch by spinning up a dynamic environment for your merge requests.
2019-07-07 11:18:12 +05:30
- Allow designers and product managers 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#the-entire-devops-lifecycle).
2018-12-05 23:21:45 +05:30
- Allow you to deploy your changes wherever you want.
![Review Apps Workflow](img/continuous-delivery-review-apps.svg)
2019-07-31 22:56:46 +05:30
In the above example:
2017-08-17 22:00:37 +05:30
2019-09-04 21:01:54 +05:30
- A Review App is built every time a commit is pushed to `topic branch`.
2019-07-31 22:56:46 +05:30
- The reviewer fails two reviews before passing the third review.
2021-01-29 00:20:46 +05:30
- After the review has passed, `topic branch` is merged into `master` where it is deployed to staging.
2019-12-21 20:55:43 +05:30
- After having been approved in staging, the changes that were merged into `master` are deployed in to production.
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
## How Review Apps work
2019-07-31 22:56:46 +05:30
2020-05-24 23:13:21 +05:30
A Review App is a mapping of a branch with an [environment](../environments/index.md).
2021-01-03 14:25:43 +05:30
Access to the Review App is made available as a link on the [merge request](../../user/project/merge_requests/index.md) relevant to the branch.
2019-07-31 22:56:46 +05:30
The following is an example of a merge request with an environment set dynamically.
2017-08-17 22:00:37 +05:30
![Review App in merge request](img/review_apps_preview_in_mr.png)
2019-07-31 22:56:46 +05:30
In this example, a branch was:
2018-12-05 23:21:45 +05:30
- Successfully built.
- Deployed under a dynamic environment that can be reached by clicking on the **View app** button.
2019-09-30 21:07:59 +05:30
After adding Review Apps to your workflow, you follow the branched Git flow. That is:
2020-11-24 15:15:51 +05:30
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.
2019-09-30 21:07:59 +05:30
1. Click on the link provided in the merge request related to the branch to see the changes live.
2019-07-31 22:56:46 +05:30
## Configuring Review Apps
2018-12-05 23:21:45 +05:30
2020-05-24 23:13:21 +05:30
Review Apps are built on [dynamic environments](../environments/index.md#configuring-dynamic-environments), which allow you to dynamically create a new environment for each branch.
2018-12-05 23:21:45 +05:30
2019-07-31 22:56:46 +05:30
The process of configuring Review Apps is as follows:
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
1. Set up the infrastructure to host and deploy the Review Apps (check the [examples](#review-apps-examples) below).
2020-11-24 15:15:51 +05:30
1. [Install](https://docs.gitlab.com/runner/install/) and [configure](https://docs.gitlab.com/runner/commands/) a runner to do deployment.
2020-03-13 15:44:24 +05:30
1. Set up a job in `.gitlab-ci.yml` that uses the [predefined CI environment variable](../variables/README.md) `${CI_COMMIT_REF_NAME}`
to create dynamic environments and restrict it to run only on branches.
Alternatively, you can get a YML template for this job by [enabling review apps](#enable-review-apps-button) for your project.
2020-05-24 23:13:21 +05:30
1. Optionally, set a job that [manually stops](../environments/index.md#stopping-an-environment) the Review Apps.
2017-08-17 22:00:37 +05:30
2020-03-13 15:44:24 +05:30
### Enable Review Apps button
2020-06-23 00:09:42 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118844) in GitLab 12.8.
2020-03-13 15:44:24 +05:30
When configuring Review Apps for a project, you need to add a new job to `.gitlab-ci.yml`,
as mentioned above. To facilitate this and if you are using Kubernetes, you can click
the **Enable Review Apps** button and GitLab will prompt you with a template code block that
you can copy and paste into `.gitlab-ci.yml` as a starting point. To do so:
1. Go to the project your want to create a Review App job for.
1. From the left nav, go to **Operations** > **Environments**.
1. Click on the **Enable Review Apps** button. It is available to you
if you have Developer or higher [permissions](../../user/permissions.md) to that project.
1. Copy the provided code snippet and paste it into your
`.gitlab-ci.yml` file:
![Enable Review Apps modal](img/enable_review_app_v12_8.png)
1. Feel free to tune this template to your own needs.
## Review Apps auto-stop
2020-05-24 23:13:21 +05:30
See how to [configure Review Apps environments to expire and auto-stop](../environments/index.md#environments-auto-stop)
2020-03-13 15:44:24 +05:30
after a given period of time.
2019-09-30 21:07:59 +05:30
## Review Apps examples
2017-08-17 22:00:37 +05:30
2019-07-31 22:56:46 +05:30
The following are example projects that demonstrate Review App configuration:
2018-12-05 23:21:45 +05:30
- [NGINX](https://gitlab.com/gitlab-examples/review-apps-nginx).
- [OpenShift](https://gitlab.com/gitlab-examples/review-apps-openshift).
2020-06-23 00:09:42 +05:30
Other examples of Review Apps:
- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
[Cloud Native Development with GitLab](https://www.youtube.com/watch?v=jfIyQEwrocw).
- [Review Apps for Android](https://about.gitlab.com/blog/2020/05/06/how-to-create-review-apps-for-android-with-gitlab-fastlane-and-appetize-dot-io/).
2019-03-02 22:35:43 +05:30
2019-09-30 21:07:59 +05:30
## Route Maps
2019-03-02 22:35:43 +05:30
2019-07-31 22:56:46 +05:30
> Introduced in GitLab 8.17. In GitLab 11.5, the file links are available in the merge request widget.
2019-03-02 22:35:43 +05:30
Route Maps allows you to go directly from source files
2020-05-24 23:13:21 +05:30
to public pages on the [environment](../environments/index.md) defined for
2019-07-31 22:56:46 +05:30
Review Apps.
Once set up, the review app link in the merge request
2019-03-02 22:35:43 +05:30
widget can take you directly to the pages changed, making it easier
and faster to preview proposed modifications.
2019-07-31 22:56:46 +05:30
Configuring Route Maps involves telling GitLab how the paths of files
2019-03-02 22:35:43 +05:30
in your repository map to paths of pages on your website using a Route Map.
Once set, GitLab will display **View on ...** buttons, which will take you
to the pages changed directly from merge requests.
2020-01-01 13:55:28 +05:30
To set up a route map, add a file inside the repository at `.gitlab/route-map.yml`,
2019-03-02 22:35:43 +05:30
which contains a YAML array that maps `source` paths (in the repository) to `public`
paths (on the website).
2019-09-30 21:07:59 +05:30
### Route Maps example
2019-03-02 22:35:43 +05:30
2019-07-31 22:56:46 +05:30
The following is an example of a route map for [Middleman](https://middlemanapp.com),
2019-03-02 22:35:43 +05:30
a static site generator (SSG) used to build [GitLab's website](https://about.gitlab.com),
deployed from its [project on GitLab.com](https://gitlab.com/gitlab-com/www-gitlab-com):
```yaml
# Team data
2020-11-24 15:15:51 +05:30
- source: 'data/team.yml' # data/team.yml
public: 'team/' # team/
2019-03-02 22:35:43 +05:30
# Blogposts
2020-11-24 15:15:51 +05:30
- source: /source\/posts\/([0-9]{4})-([0-9]{2})-([0-9]{2})-(.+?)\..*/ # source/posts/2017-01-30-around-the-world-in-6-releases.html.md.erb
public: '\1/\2/\3/\4/' # 2017/01/30/around-the-world-in-6-releases/
2019-03-02 22:35:43 +05:30
# HTML files
2020-11-24 15:15:51 +05:30
- source: /source\/(.+?\.html).*/ # source/index.html.haml
public: '\1' # index.html
2019-03-02 22:35:43 +05:30
# Other files
2020-11-24 15:15:51 +05:30
- source: /source\/(.*)/ # source/images/blogimages/around-the-world-in-6-releases-cover.png
public: '\1' # images/blogimages/around-the-world-in-6-releases-cover.png
2019-03-02 22:35:43 +05:30
```
2019-07-31 22:56:46 +05:30
Mappings are defined as entries in the root YAML array, and are identified by a `-` prefix. Within an entry, there is a hash map with two keys:
2019-03-02 22:35:43 +05:30
- `source`
2019-07-31 22:56:46 +05:30
- A string, starting and ending with `'`, for an exact match.
- A regular expression, starting and ending with `/`, for a pattern match:
- The regular expression needs to match the entire source path - `^` and `$` anchors are implied.
- Can include capture groups denoted by `()` that can be referred to in the `public` path.
- Slashes (`/`) can, but don't have to, be escaped as `\/`.
- Literal periods (`.`) should be escaped as `\.`.
- `public`, a string starting and ending with `'`.
- Can include `\N` expressions to refer to capture groups in the `source` regular expression in order of their occurrence, starting with `\1`.
2019-03-02 22:35:43 +05:30
The public path for a source path is determined by finding the first
`source` expression that matches it, and returning the corresponding
`public` path, replacing the `\N` expressions with the values of the
`()` capture groups if appropriate.
In the example above, the fact that mappings are evaluated in order
of their definition is used to ensure that `source/index.html.haml`
will match `/source\/(.+?\.html).*/` instead of `/source\/(.*)/`,
and will result in a public path of `index.html`, instead of
`index.html.haml`.
2021-01-29 00:20:46 +05:30
After you have the route mapping set up, it will take effect in the following locations:
2019-03-02 22:35:43 +05:30
2019-07-31 22:56:46 +05:30
- In the merge request widget. The:
- **View app** button will take you to the environment URL set in `.gitlab-ci.yml`.
- Dropdown will list the first 5 matched items from the route map, but you can filter them if more
than 5 are available.
2019-03-02 22:35:43 +05:30
![View app file list in merge request widget](img/view_on_mr_widget.png)
- In the diff for a merge request, comparison, or commit.
2019-10-12 21:52:04 +05:30
!["View on env" button in merge request diff](img/view_on_env_mr.png)
2019-03-02 22:35:43 +05:30
- In the blob file view.
2019-10-12 21:52:04 +05:30
!["View on env" button in file view](img/view_on_env_blob.png)
2019-07-31 22:56:46 +05:30
2019-09-30 21:07:59 +05:30
## Visual Reviews **(STARTER)**
2019-09-04 21:01:54 +05:30
2021-01-03 14:25:43 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10761) in GitLab Starter 12.0.
> - It's [deployed behind a feature flag](../../user/feature_flags.md), enabled by default.
> - It's enabled on GitLab.com.
> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-visual-reviews). **(STARTER ONLY)**
2019-09-04 21:01:54 +05:30
2021-01-03 14:25:43 +05:30
With Visual Reviews, members of any team (Product, Design, Quality, and so on) can provide feedback comments through a form in your review apps. The comments are added to the merge request that triggered the review app.
2019-09-04 21:01:54 +05:30
2021-01-03 14:25:43 +05:30
### Using Visual Reviews
2019-09-04 21:01:54 +05:30
2021-01-03 14:25:43 +05:30
After Visual Reviews has been [configured](#configure-review-apps-for-visual-reviews) for the
Review App, the Visual Reviews feedback form is overlaid on the right side of every page.
2020-01-01 13:55:28 +05:30
2021-01-03 14:25:43 +05:30
![Visual review feedback form](img/toolbar_feedback_form_v13_5.png)
To use the feedback form to make a comment in the merge request:
1. Click the **Review** tab on the right side of a page.
1. Make a comment on the visual review. You can make use of all the
[Markdown annotations](../../user/markdown.md) that are also available in
merge request comments.
1. Enter your personal information:
- If [`data-require-auth`](#authentication-for-visual-reviews) is `true`, you must enter your [personal access token](../../user/profile/personal_access_tokens.md).
- Otherwise, enter your name, and optionally your email.
1. Click **Send feedback**.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
To see Visual reviews in action, see the [Visual Reviews Walk through](https://youtu.be/1_tvWTlPfM4).
### Configure Review Apps for Visual Reviews
2020-01-01 13:55:28 +05:30
2019-09-30 21:07:59 +05:30
The feedback form is served through a script you add to pages in your Review App.
If you have [Developer permissions](../../user/permissions.md) to the project,
you can access it by clicking the **Review** button in the **Pipeline** section
2020-04-08 14:13:33 +05:30
of the merge request. The form modal will also show a dropdown for changed pages
if [route maps](#route-maps) are configured in the project.
2019-09-04 21:01:54 +05:30
2019-09-30 21:07:59 +05:30
![review button](img/review_button.png)
2019-09-04 21:01:54 +05:30
2020-05-24 23:13:21 +05:30
The provided script should be added to the `<head>` of your application and
2021-01-03 14:25:43 +05:30
consists of some project and merge request specific values. Here's how it
looks for a project with code hosted in a project on GitLab.com:
2019-09-30 21:07:59 +05:30
```html
<script
data-project-id='11790219'
data-merge-request-id='1'
2021-01-03 14:25:43 +05:30
data-mr-url='https://gitlab.com'
2019-09-30 21:07:59 +05:30
data-project-path='sarah/review-app-tester'
2020-04-22 19:07:51 +05:30
data-require-auth='true'
2019-09-30 21:07:59 +05:30
id='review-app-toolbar-script'
2021-01-03 14:25:43 +05:30
src='https://gitlab.com/assets/webpack/visual_review_toolbar.js'>
2019-09-30 21:07:59 +05:30
</script>
```
2019-09-04 21:01:54 +05:30
2019-09-30 21:07:59 +05:30
Ideally, you should use [environment variables](../variables/predefined_variables.md)
to replace those values at runtime when each review app is created:
- `data-project-id` is the project ID, which can be found by the `CI_PROJECT_ID`
variable.
- `data-merge-request-id` is the merge request ID, which can be found by the
`CI_MERGE_REQUEST_IID` variable. `CI_MERGE_REQUEST_IID` is available only if
[`only: [merge_requests]`](../merge_request_pipelines/index.md)
is used and the merge request is created.
- `data-mr-url` is the URL of the GitLab instance and will be the same for all
review apps.
- `data-project-path` is the project's path, which can be found by `CI_PROJECT_PATH`.
2021-01-03 14:25:43 +05:30
- `data-require-auth` is optional for public projects but required for [private and internal ones](#authentication-for-visual-reviews). If this is set to `true`, the user will be required to enter their [personal access token](../../user/profile/personal_access_tokens.md) instead of their name and email.
2019-09-30 21:07:59 +05:30
- `id` is always `review-app-toolbar-script`, you don't need to change that.
- `src` is the source of the review toolbar script, which resides in the
respective GitLab instance and will be the same for all review apps.
2021-01-03 14:25:43 +05:30
For example, in a Ruby application with code hosted on in a project GitLab.com, you would need to have this script:
2019-09-30 21:07:59 +05:30
```html
<script
data-project-id="ENV['CI_PROJECT_ID']"
data-merge-request-id="ENV['CI_MERGE_REQUEST_IID']"
2021-01-03 14:25:43 +05:30
data-mr-url='https://gitlab.com'
2019-09-30 21:07:59 +05:30
data-project-path="ENV['CI_PROJECT_PATH']"
id='review-app-toolbar-script'
2021-01-03 14:25:43 +05:30
src='https://gitlab.com/assets/webpack/visual_review_toolbar.js'>
2019-09-30 21:07:59 +05:30
</script>
```
2019-09-04 21:01:54 +05:30
2019-09-30 21:07:59 +05:30
Then, when your app is deployed via GitLab CI/CD, those variables should get
replaced with their real values.
2019-09-04 21:01:54 +05:30
2020-01-01 13:55:28 +05:30
### Determining merge request ID
The visual review tools retrieve the merge request ID from the `data-merge-request-id`
data attribute included in the `script` HTML tag used to add the visual review tools
to your review app.
After determining the ID for the merge request to link to a visual review app, you
can supply the ID by either:
2020-05-24 23:13:21 +05:30
- Hard-coding it in the script tag via the data attribute `data-merge-request-id` of the app.
2020-01-01 13:55:28 +05:30
- Dynamically adding the `data-merge-request-id` value during the build of the app.
- Supplying it manually through the visual review form in the app.
2021-01-03 14:25:43 +05:30
### Enable or disable Visual Reviews **(STARTER ONLY)**
2020-04-22 19:07:51 +05:30
2021-01-03 14:25:43 +05:30
Visual Reviews is deployed behind a feature flag that is **enabled by default**.
[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md)
can opt to disable it.
2020-04-22 19:07:51 +05:30
2021-01-03 14:25:43 +05:30
To disable it:
2020-04-22 19:07:51 +05:30
2021-01-03 14:25:43 +05:30
```ruby
Feature.disable(:anonymous_visual_review_feedback)
```
2019-09-04 21:01:54 +05:30
2021-01-03 14:25:43 +05:30
To enable it:
2019-09-04 21:01:54 +05:30
2021-01-03 14:25:43 +05:30
```ruby
Feature.enable(:anonymous_visual_review_feedback)
```
2019-09-04 21:01:54 +05:30
2021-01-03 14:25:43 +05:30
### Authentication for Visual Reviews
2019-09-30 21:07:59 +05:30
2021-01-03 14:25:43 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/42750#note_317271120) in GitLab 12.10.
To enable visual reviews for private and internal projects, set the
[`data-require-auth` variable](#enable-or-disable-visual-reviews) to `true`. When enabled,
the user must enter a [personal access token](../../user/profile/personal_access_tokens.md)
with `api` scope before submitting feedback.
2019-09-04 21:01:54 +05:30
2021-01-03 14:25:43 +05:30
This same method can be used to require authentication for any public projects.
2019-09-04 21:01:54 +05:30
2019-07-31 22:56:46 +05:30
## Limitations
2020-05-24 23:13:21 +05:30
Review App limitations are the same as [environments limitations](../environments/index.md#limitations).