doc/ci/review_apps/_index.md
{{< details >}}
{{< /details >}}
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.
Built on dynamic environments, review apps provide a unique environment for each branch or merge request.
These environments help streamline the development workflow by:
[!note] If you have a Kubernetes cluster, you can set up review apps automatically using Auto DevOps.
A review app workflow could be similar to:
%%{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
with 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
Configure review apps when you want to provide a preview environment of your application for each branch or merge request.
Prerequisites:
To configure review apps in your project:
In the top bar, select Search or go to and find your project.
Select Build > Pipeline editor.
In your .gitlab-ci.yml file, add a job that creates a dynamic environment.
You can use a predefined CI/CD variable to differentiate
each environment. For example, using the CI_COMMIT_REF_SLUG predefined variable:
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
Optional. Add when: manual to the job to only deploy review apps manually.
Optional. Add a job to stop the review app when it's no longer needed.
Enter a commit message and select Commit changes.
GitLab provides a built-in template that's configured for merge request pipelines by default.
To use and customize this template:
In the top bar, select Search or go to and find your project.
Select Operate > Environments.
Select Enable review apps.
From the Enable Review Apps dialog that appears, copy the YAML template:
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"
Select Build > Pipeline editor.
Paste the template into your .gitlab-ci.yml file.
Customize the template based on your deployment needs:
For example, for a deployment to Heroku:
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.
Enter a commit message and select Commit changes.
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.
To configure review apps to automatically stop when the associated merge request is merged or the branch is deleted:
on_stop keyword to your deployment job.environment:action: stop.when: manual to the stop job to make it possible to
manually stop the review app at any time.For example:
# 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_review_app job
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"
To configure review apps to stop automatically after a period of time,
add the auto_stop_in keyword to your deployment job:
# 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
To deploy and access review apps:
These projects demonstrate different review app implementations:
Other examples of review apps:
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.
When configured, route maps add contextual links that let you view the review app version of files that match your mapping patterns. These links appear in:
To set up route maps:
.gitlab/route-map.yml.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:
- 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:
For pattern matching with regular expressions:
^ and $ anchors are implied).() that can be referenced in the public path.\N expressions in order of occurrence (\1, \2, etc.)./) as \/ and periods (.) as \..GitLab evaluates mappings in order of definition. The first source expression that matches determines the public path.
The following example shows a route map for Middleman, a static site generator used for the GitLab website:
# Team data
- source: 'data/team.yml' # data/team.yml
public: 'team/' # team/
# Blogposts
- 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/
# HTML files
- source: /source\/(.+?\.html).*/ # source/index.html.haml
public: '\1' # index.html
# Other files
- 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
In this example:
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.Use route maps to navigate directly from source files to their corresponding pages in your review app.
Prerequisites:
.gitlab/route-map.yml.To view mapped pages from the merge request widget:
To view a mapped page from a file:
To view mapped pages from a commit:
[!note] Merged results pipelines create an internal commit that merges your branch with the target branch. To access review app links for these pipelines, use the commit from the Pipelines tab, not the Commits tab.