Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 36 ยท Environments and Deployments

Review Apps and Dynamic Environments

Create a live preview for every merge request with dynamic environment names, CI_COMMIT_REF_SLUG, stop jobs and auto_stop_in, and learn the cost and safety rules.

Reading a diff tells you what changed in the code. Seeing the running result tells you whether the change works. A review app is a temporary deployment created for one branch or merge request, so reviewers, designers and testers can click through the real change before it is merged.

In GitLab a review app is not a special feature. It is an ordinary deployment job whose environment name is built from a variable, which makes the environment dynamic. This lesson explains how the name is built, how the environment is linked to the merge request, and how to clean up. The YAML is read-only because your deployment target is yours to choose; the runnable examples reproduce the slug rules and the expiry logic.

A dynamic environment name

A static environment (production) has one name for ever. A dynamic one uses a predefined variable so every branch gets its own:

YAML
deploy_review:
  stage: deploy
  script:
    - ./scripts/deploy-review.sh "$CI_COMMIT_REF_SLUG"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_COMMIT_REF_SLUG.review.example.com
    on_stop: stop_review
    auto_stop_in: 3 days
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Three details matter:

  • The review/ prefix groups all review environments in a folder in the environment list, and it lets you scope variables with the wildcard review/*.
  • CI_COMMIT_REF_SLUG is the branch or tag name made safe for URLs and DNS: lowercase, letters and numbers kept, every other character turned into -, shortened to 63 characters, with no hyphen at the start or end. A branch called Feature/Login_Page becomes feature-login-page.
  • The url can use the same variable, so each review app gets its own host name. You need a wildcard DNS record (*.review.example.com) pointing at the place where the apps run.

On a merge request page, GitLab shows a View app button for the deployment, so the preview is one click away from the discussion.

The stop job

If review environments were never removed, every merge request would leave a running copy of your application behind. The stop job is the cleanup:

YAML
stop_review:
  stage: deploy
  script:
    - ./scripts/destroy-review.sh "$CI_COMMIT_REF_SLUG"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: manual

GitLab runs it automatically when the merge request is merged or closed and the branch is deleted, and you can also run it by hand from the environment page. Two things commonly go wrong: the name of the stop job must match the deploy job exactly, and the stop job must be able to run without the checked out branch (the branch may already be gone), so set GIT_STRATEGY: none if the destroy script does not need your code:

YAML
stop_review:
  variables:
    GIT_STRATEGY: none

auto_stop_in adds a safety net. If nobody touches the environment for the given time, GitLab runs the stop job itself. Values read like "1 day", "3 days" or "1 week". Redeploying the environment starts the timer again.

flowchart LR
  MR["open merge request"] --> D["deploy_review job"]
  D --> E["environment review/branch-name"]
  E --> V["reviewers click View app"]
  V --> M{"merged or expired?"}
  M -->|"yes"| S["stop_review job"]
  S --> X["environment stopped"]

The environment lives from the first deployment until the stop job removes it.

What to run in a review app

How much a review app costs depends on what you deploy. Practical options, from cheap to heavy:

  1. Static preview. Build the site, copy it into a folder named after the branch, serve it from one web server. Almost free.
  2. Container per branch. Start the image you just built in a shared cluster namespace named after the slug. The container registry holds the image (see Container Registry).
  3. Full stack. A namespace with its own database seeded from sample data. Most realistic, most expensive, so use short auto_stop_in values.

Whatever you choose, treat review apps as untrusted and temporary. They run unreviewed code, so keep them away from production data, use separate credentials and scope them with the review/* variable scope. Never point a review app at the production database to "make the data look real".

Environment variables and secrets for review apps

Because the review environment name starts with review/, a variable with scope review/* is visible there and nowhere else. Put sandbox API keys and a throwaway database password under that scope. The production values stay scoped to production, so a bug in an experimental branch cannot leak them. The details of masking and protecting values are in CI Variables and Secrets Security.

Stand-in: the slug rule

This function applies the slug rule described above. It is a model written for teaching; GitLab's own implementation is the reference, so check the documentation of your version if you rely on exact edge cases.

JS Branch names to slugs

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that two different branches can produce the same slug (feature/login and feature-login). That is rare, but it is a good reason to include the merge request number in names when a clash would be harmful.

Stand-in: automatic expiry

The second example models auto_stop_in. Each environment has a deadline; a sweep stops every environment whose deadline is in the past, and a new deployment moves the deadline forward.

JS auto_stop_in sweep

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What makes an environment dynamic?

    A name like review/$CI_COMMIT_REF_SLUG yields a new environment for every branch, so the environment set grows and shrinks with your branches.
  2. 2. The branch is called Fix/Header_Bug. What is its CI_COMMIT_REF_SLUG?

    The slug is lowercase, and every character that is not a letter or number becomes a hyphen.
  3. 3. Why should the stop job often set GIT_STRATEGY: none?

    After a merge the source branch is usually removed, so a normal checkout of it would fail. The destroy script only needs the slug.
  4. 4. Which variable scope limits a sandbox API key to review apps?

    The wildcard matches environment names that start with review/ and nothing else.
  5. 5. What does auto_stop_in protect you from?

    When nobody redeploys the environment before the deadline, GitLab runs its stop job automatically.

Summary

  • A review app is a normal deployment with a dynamic name such as review/$CI_COMMIT_REF_SLUG.
  • GitLab shows a View app link on the merge request; the slug makes the host name unique.
  • Always pair the deploy job with a stop job (on_stop, action: stop) and add auto_stop_in as a safety net.
  • Review apps run unreviewed code: use separate credentials scoped to review/* and never production data.

Next: Deployment Strategies and Rollbacks