diff --git a/app/assets/javascripts/environments/components/enable_review_app_modal.vue b/app/assets/javascripts/environments/components/enable_review_app_modal.vue
index aab19cf919ee797d449f500370c51c5e2f9a93e2..67682121e89b36f7c1ce748cf4cdec82a462bab3 100644
--- a/app/assets/javascripts/environments/components/enable_review_app_modal.vue
+++ b/app/assets/javascripts/environments/components/enable_review_app_modal.vue
@@ -54,10 +54,10 @@ export default {
},
i18n,
configuringReviewAppsPath: helpPagePath('ci/review_apps/_index.md', {
- anchor: 'configuring-review-apps',
+ anchor: 'configure-review-apps',
}),
reviewAppsExamplesPath: helpPagePath('ci/review_apps/_index.md', {
- anchor: 'review-apps-examples',
+ anchor: 'example-implementations',
}),
};
diff --git a/doc/ci/review_apps/_index.md b/doc/ci/review_apps/_index.md
index a31d22a3a88f143604258104d906b972550f2897..eb5112dd9a205d578762c9d1f997b64b9f12fdf3 100644
--- a/doc/ci/review_apps/_index.md
+++ b/doc/ci/review_apps/_index.md
@@ -2,6 +2,7 @@
stage: Verify
group: Pipeline Execution
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
+description: Set up and use review apps to create temporary environments for testing changes before merging.
title: Review apps
---
@@ -12,92 +13,238 @@ title: Review apps
{{< /details >}}
-Review apps are a collaboration tool that provide an environment to showcase product changes.
+Review apps are temporary testing environments that are created automatically for each branch or merge request.
+You can preview and validate changes without needing to set up a local development environment.
-{{< alert type="note" >}}
-
-If you have a Kubernetes cluster, you can automate this feature in your applications
-by using [Auto DevOps](../../topics/autodevops/_index.md).
+Built on [dynamic environments](../environments/_index.md#create-a-dynamic-environment),
+review apps provide a unique environment for each branch or merge request.
-{{< /alert >}}
+
-Review apps:
+These environments help streamline the development workflow by:
-- 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 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](https://about.gitlab.com/stages-devops-lifecycle/).
-- Allow you to deploy your changes wherever you want.
+- Eliminating the need for local setup to test changes.
+- Providing consistent environments for all team members.
+- Enabling stakeholders to preview changes with a URL.
+- Facilitating faster feedback cycles before changes reach production.
-
+{{< alert type="note" >}}
-In the previous example:
+If you have a Kubernetes cluster, you can set up review apps automatically using [Auto DevOps](../../topics/autodevops/_index.md).
-- A review app is built every time a commit is pushed to `topic branch`.
-- The reviewer fails two reviews before passing the third review.
-- After the review passes, `topic branch` is merged into the default branch, where it's deployed to staging.
-- After its approval in staging, the changes that were merged into the default branch are deployed to production.
+{{< /alert >}}
-## How review apps work
+## Review app workflow
+
+A review app workflow could be similar to:
+
+```mermaid
+%%{init: { "fontFamily": "GitLab Sans" }}%%
+flowchart TD
+ accTitle: Review app workflow
+ accDescr: Diagram showing how review apps fit into the GitLab development workflow.
+
+ subgraph Development["Development"]
+ TopicBranch["Create topic branch"]
+ Commit["Make code changes"]
+ CreateMR["Create merge request"]
+ end
+
+ subgraph ReviewAppCycle["Review app cycle"]
+ direction LR
+ Pipeline["CI/CD pipeline runs"]
+ ReviewApp["Review app deployed"]
+ Testing["Review and testing"]
+ Feedback["Feedback provided"]
+ NewCommits["Address feedback\nwith new commits"]
+ end
+
+ subgraph Deployment["Deployment"]
+ Approval["Merge request approved"]
+ Merge["Merged to default branch"]
+ Production["Deployed to production"]
+ end
+
+ TopicBranch --> Commit
+ Commit --> CreateMR
+ CreateMR --> Pipeline
+
+ Pipeline --> ReviewApp
+ ReviewApp --> Testing
+ Testing --> Feedback
+ Feedback --> NewCommits
+ NewCommits --> Pipeline
+
+ Testing --> Approval
+ Approval --> Merge
+ Merge --> Production
+
+ classDef devNode fill:#e1e1e1,stroke:#666,stroke-width:1px
+ classDef reviewNode fill:#fff0dd,stroke:#f90,stroke-width:1px
+ classDef finalNode fill:#d5f5ff,stroke:#0095cd,stroke-width:1px
+
+ class TopicBranch,Commit,CreateMR devNode
+ class Pipeline,ReviewApp,Testing,Feedback,NewCommits reviewNode
+ class Approval,Merge,Production finalNode
+```
-A review app is a mapping of a branch with an [environment](../environments/_index.md).
-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.
+## Configure review apps
-The following is an example of a merge request with an environment set dynamically.
+Configure review apps when you want to provide a preview environment of your application for each branch or merge request.
-
+Prerequisites:
-In this example, a branch was:
+- You must have at least the Developer role for the project.
+- You must have CI/CD pipelines available in the project.
+- You must set up the infrastructure to host and deploy the review apps.
-- Successfully built.
-- Deployed under a dynamic environment that can be reached by selecting **View app**.
+To configure review apps in your project:
-After adding review apps to your workflow, you follow the branched Git flow. That is:
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Build > Pipeline editor**.
+1. In your `.gitlab-ci.yml` file, add a job that creates a [dynamic environment](../environments/_index.md#create-a-dynamic-environment).
+ You can use a [predefined CI/CD variable](../variables/predefined_variables.md) to differentiate
+ each environment. For example, using the `CI_COMMIT_REF_SLUG` predefined variable:
-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. To view the changes live, select the link in the merge request related to the branch.
+ ```yaml
+ review_app:
+ stage: deploy
+ script:
+ - echo "Deploy to review app environment"
+ # Add your deployment commands here
+ environment:
+ name: review/$CI_COMMIT_REF_SLUG
+ url: https://$CI_COMMIT_REF_SLUG.example.com
+ rules:
+ - if: $CI_COMMIT_BRANCH && $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
+ ```
-## Configuring review apps
+1. Optional. Add `when: manual` to the job to only deploy review apps manually.
+1. Optional. Add a job to [stop the review app](#stop-review-apps) when it's no longer needed.
+1. Enter a commit message and select **Commit changes**.
-Review apps are built on [dynamic environments](../environments/_index.md#create-a-dynamic-environment), which allow you to dynamically create a new environment for each branch.
+### Use the review apps template
-The process of configuring review apps is as follows:
+GitLab provides a built-in template that's configured for merge request pipelines by default.
-1. Set up the infrastructure to host and deploy the review apps (check the [examples](#review-apps-examples) below).
-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 CI/CD variable](../variables/_index.md) `${CI_COMMIT_REF_SLUG}`
- to create dynamic environments and restrict it to run only on branches.
- Alternatively, you can get a YAML template for this job by [enabling review apps](#enable-review-apps-button) for your project.
-1. Optionally, set a job that [manually stops](../environments/_index.md#stopping-an-environment) the review apps.
+To use and customize this template:
-### Enable review apps button
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Operate > Environments**.
+1. Select **Enable review apps**.
+1. From the **Enable Review Apps** dialog that appears, copy the YAML template:
+
+ ```yaml
+ deploy_review:
+ stage: deploy
+ script:
+ - echo "Add script here that deploys the code to your infrastructure"
+ environment:
+ name: review/$CI_COMMIT_REF_NAME
+ url: https://$CI_ENVIRONMENT_SLUG.example.com
+ rules:
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+ ```
+
+1. Select **Build > Pipeline editor**.
+1. Paste the template into your `.gitlab-ci.yml` file.
+1. Customize the template based on your deployment needs:
+
+ - Modify the deployment script and environment URL to work with your infrastructure.
+ - Adjust [the rules section](../jobs/job_rules.md) if you want to trigger review apps
+ for branches even without merge requests.
+
+ For example, for a deployment to Heroku:
+
+ ```yaml
+ deploy_review:
+ stage: deploy
+ image: ruby:latest
+ script:
+ - apt-get update -qy
+ - apt-get install -y ruby-dev
+ - gem install dpl
+ - dpl --provider=heroku --app=$HEROKU_APP_NAME --api-key=$HEROKU_API_KEY
+ environment:
+ name: review/$CI_COMMIT_REF_NAME
+ url: https://$HEROKU_APP_NAME.herokuapp.com
+ on_stop: stop_review_app
+ rules:
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+ ```
+
+ This configuration sets up an automated deployment to Heroku whenever a pipeline runs for a merge request.
+ It uses Ruby's `dpl` deployment tool to handle the process, and creates a dynamic review environment that can be accessed through the specified URL.
+
+1. Enter a commit message and select **Commit changes**.
+
+### Stop review apps
+
+You can configure your review apps to be stopped either manually or automatically to conserve resources.
+
+For more information about stopping environments for review apps, see [Stopping an environment](../environments/_index.md#stopping-an-environment).
+
+#### Auto-stop review apps on merge
+
+To configure review apps to automatically stop when the associated merge request is merged
+or the branch is deleted:
+
+1. Add the [`on_stop`](../yaml/_index.md#environmenton_stop) keyword to your deployment job.
+1. Create a stop job with the [`environment:action: stop`](../yaml/_index.md#environmentaction).
+1. Optional. Add [`when: manual`](../yaml/_index.md#when) to the stop job to make it possible to
+ manually stop the review app at any time.
+
+For example:
-When configuring review apps for a project, you add a new job to the `.gitlab-ci.yml` file,
-as mentioned above. To facilitate this, and if you are using Kubernetes, you can select
-**Enable review apps** and GitLab prompts you with a template code block that
-you can copy and paste into `.gitlab-ci.yml` as a starting point.
+```yaml
+# In your .gitlab-ci.yml file
+deploy_review:
+ # Other configuration...
+ environment:
+ name: review/${CI_COMMIT_REF_NAME}
+ url: https://${CI_ENVIRONMENT_SLUG}.example.com
+ on_stop: stop_review_app # References the stop job below
+
+stop_review_app:
+ stage: deploy
+ script:
+ - echo "Stop review app"
+ # Add your cleanup commands here
+ environment:
+ name: review/${CI_COMMIT_REF_NAME}
+ action: stop
+ when: manual # Makes this job manually triggerable
+ rules:
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+```
-Prerequisites:
+#### Time-based automatic stop
-- You need at least the Developer role for the project.
+To configure review apps to stop automatically after a period of time,
+add the [`auto_stop_in`](../yaml/_index.md#environmentauto_stop_in) keyword to your deployment job:
-To use the review apps template:
+```yaml
+# In your .gitlab-ci.yml file
+review_app:
+ script: deploy-review-app
+ environment:
+ name: review/$CI_COMMIT_REF_SLUG
+ auto_stop_in: 1 week # Stops after one week of inactivity
+ rules:
+ - if: $CI_MERGE_REQUEST_ID
+```
-1. On the left sidebar, select **Search or go to** and
- find the project you want to create a review app job for.
-1. Select **Operate > Environments**.
-1. Select **Enable review apps**.
-1. Follow the instructions in the dialog.
- You can edit the provided `.gitlab-ci.yml` template as needed.
+## View review apps
-## Review apps auto-stop
+To deploy and access review apps:
-See how to [configure review apps environments to expire and auto-stop](../environments/_index.md#stop-an-environment-after-a-certain-time-period)
-after a given period of time.
+1. Go to your merge request.
+1. Optional. If the review app job is manual, select **Run** ({{< icon name="play" >}}) to trigger the deployment.
+1. When the pipeline finishes, select **View app** to open the review app in your browser.
-## Review apps examples
+## Example implementations
-The following are example projects that demonstrate review app configuration:
+These projects demonstrate different review app implementations:
| Project | Configuration file |
| --------------------------------------------------------------------------------------- | ------------------ |
@@ -110,34 +257,54 @@ The following are example projects that demonstrate review app configuration:
Other examples of review apps:
--
+-
[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/).
-## Route Maps
+## Route maps
+
+Route maps let you navigate directly from source files to their corresponding public pages in the review app environment.
+This feature makes it easier to preview specific changes in your merge requests.
-Route Maps allows you to go directly from source files
-to public pages on the [environment](../environments/_index.md) defined for
-review apps.
+When configured, route maps enhance the review app experience by adding links to review app versions
+of the changed files in:
-Once set up, the review app link in the merge request
-widget can take you directly to the pages changed, making it easier
-and faster to preview proposed modifications.
+- The merge request widget.
+- Commit and file views.
-Configuring Route Maps involves telling GitLab how the paths of files
-in your repository map to paths of pages on your website using a Route Map.
-When you configure Route Maps, **View on** buttons are displayed.
-Select these buttons to go to the pages changed directly from merge requests.
+### Configure route maps
-To set up a route map, add a file inside the repository at `.gitlab/route-map.yml`,
-which contains a YAML array that maps `source` paths (in the repository) to `public`
-paths (on the website).
+To set up route maps:
-### Route Maps example
+1. Create a file in your repository at `.gitlab/route-map.yml`.
+1. Define mappings between source paths (in your repository) and public paths (on your review app infrastructure or website).
-The following is an example of a route map for [Middleman](https://middlemanapp.com),
-a static site generator (SSG) used to build the [GitLab website](https://about.gitlab.com),
-deployed from its [project on GitLab.com](https://gitlab.com/gitlab-com/www-gitlab-com):
+The route map is a YAML array where each entry maps a `source` path to a `public` path.
+
+Each mapping in the route map follows this format:
+
+```yaml
+- source: 'path/to/source/file' # Source file in repository
+ public: 'path/to/public/page' # Public page on the website
+```
+
+You can use two types of mapping:
+
+- **Exact match**: String literals enclosed in single quotes
+- **Pattern match**: Regular expressions enclosed in forward slashes
+
+For pattern matching with regular expressions:
+
+- The regex must match the entire source path (`^` and `$` anchors are implied).
+- You can use capture groups `()` that can be referenced in the `public` path.
+- Reference capture groups using `\N` expressions in order of occurrence (`\1`, `\2`, etc.).
+- Escape slashes (`/`) as `\/` and periods (`.`) as `\.`.
+
+GitLab evaluates mappings in order of definition. The first `source` expression that matches determines the `public` path.
+
+### Example route map
+
+The following example shows a route map for [Middleman](https://middlemanapp.com), a static site generator used for the [GitLab website](https://about.gitlab.com):
```yaml
# Team data
@@ -157,38 +324,33 @@ deployed from its [project on GitLab.com](https://gitlab.com/gitlab-com/www-gitl
public: '\1' # images/blogimages/around-the-world-in-6-releases-cover.png
```
-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:
+In this example:
+
+- The mappings are evaluated in order.
+- The third mapping ensures that `source/index.html.haml` matches `/source\/(.+?\.html).*/` instead of the catch-all `/source\/(.*)/`.
+ This produces a public path of `index.html` instead of `index.html.haml`.
+
+### View mapped pages
-- `source`
- - 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`.
+After you configure route maps, you can find links to the mapped pages after the next
+review app deployment.
-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.
+To view mapped pages:
-In the example above, the fact that mappings are evaluated in order
-of their definition is used to ensure that `source/index.html.haml`
-matches `/source\/(.+?\.html).*/` instead of `/source\/(.*)/`,
-and results in a public path of `index.html`, instead of
-`index.html.haml`.
+- In the merge request widget, select **View app** to go to the environment URL set in the
+ `.gitlab-ci.yml` file. The list shows up to 5 matched items from the route map (with
+ filtering if more are available).
-After you have the route mapping set up, it takes effect in the following locations:
+ 
-- In the merge request widget:
- - The **View app** button takes you to the environment URL set in the `.gitlab-ci.yml` file.
- - The list shows the first 5 matched items from the route map, but you can filter them if more
- than 5 are available.
+For files in your route map:
- 
+1. In the **Changes** tab of your merge request, select **View file @ [commit]** next to a file.
+1. On the file's page, look for **View on [deployment-URL]** ({{< icon name="external-link" >}}) in the upper-right corner.
-- In the diff for a comparison or commit, by selecting **View** ({{< icon name="external-link" >}}) next to the file.
+For merge requests using merged results pipelines:
-- In the blob file view, by selecting **View** ({{< icon name="external-link" >}}) next to the file.
+1. Go to the **Pipelines** tab in your merge request.
+1. Select the commit for the latest pipeline.
+1. Select **View file @ [commit]** next to a file.
+1. On the file's page, select **View on [deployment-URL]** ({{< icon name="external-link" >}}) in the upper-right corner.
diff --git a/doc/ci/review_apps/img/continuous-delivery-review-apps_v11_4.svg b/doc/ci/review_apps/img/continuous-delivery-review-apps_v11_4.svg
deleted file mode 100644
index 90ac763a01e7ae9cb5ee6d9611e7248a585c2fc2..0000000000000000000000000000000000000000
--- a/doc/ci/review_apps/img/continuous-delivery-review-apps_v11_4.svg
+++ /dev/null
@@ -1,48 +0,0 @@
-
-
\ No newline at end of file
diff --git a/doc/ci/review_apps/img/mr_widget_route_maps_v17_11.png b/doc/ci/review_apps/img/mr_widget_route_maps_v17_11.png
new file mode 100644
index 0000000000000000000000000000000000000000..7d096f1498e128e27507cd3b17bf403e3a79b811
Binary files /dev/null and b/doc/ci/review_apps/img/mr_widget_route_maps_v17_11.png differ
diff --git a/doc/ci/review_apps/img/view_on_mr_widget_v11_5.png b/doc/ci/review_apps/img/view_on_mr_widget_v11_5.png
deleted file mode 100644
index efe023b07b56111020e68955b9db408ea29e6463..0000000000000000000000000000000000000000
Binary files a/doc/ci/review_apps/img/view_on_mr_widget_v11_5.png and /dev/null differ