Skip to main content
Version: 1.21

Preview environments using GitLab CI/CD

This section will show you how to automatically create a preview environment for your applications using Okteto and GitLab's review apps.

Pre-Requisites​

For this tutorial, we'll be using our sample movies rental application. If you're using your own application to follow along, please ensure you have your Okteto Manifest configured.

Step 1: Configure your Okteto API Token​

To deploy a preview environment with Okteto, you need to define the following environment variables:

  1. OKTETO_TOKEN: an Okteto access token
  2. OKTETO_CONTEXT: specify the URL of your Okteto instance (e.g., https://okteto.example.com)

To add the environment variables:

  1. Navigate to your GitLab repository.

  2. Go to the Settings menu on the left, and click on the CI/CD entry:

    GitLab settings, CI/CD

  3. Expand the Variables section, and click on the Add Variable button.

  4. Add OKTETO_TOKEN as the key, and your access token as the value, and press the Add Variable button:

    update variable with Okteto Token

  5. Repeat the same process to add the OKTETO_CONTEXT variables (optional)

    environment variables added

Step 2: Configure the Preview Environment on the Repository​

To tell GitLab how to deploy our preview environment, you need to create a file named .gitlab-ci.yml file at the root of the repository.

In this file, we'll define two jobs. The review creates a preview environment for every branch and a stop-review job to destroy it when merging or deleting the branch.

The flow to create a preview environment looks like this:

  1. Create a dedicated namespace for the Preview Environment
  2. Build and deploy the application using the Okteto preview defined in the repository.
  3. Add the URL of the Preview Environment to the Merge Request.

The flow to delete a preview environment looks like this:

  1. Destroy the application deployed with the Okteto preview

The .gitlab-ci.yml looks like this:

# file: .gitlab.ci.yml
image: okteto/okteto:stable

stages:
  - review

review:
  stage: review
  variables:
    APP: review-$CI_COMMIT_REF_SLUG
  script:
    - okteto preview deploy review-$CI_COMMIT_REF_SLUG --scope global --branch $CI_COMMIT_REF_NAME --repository $CI_PROJECT_URL --wait

  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://movies-review-$CI_COMMIT_REF_SLUG.okteto.example.com
    on_stop: stop-review
  only:
    - branches
  except:
    - master

stop-review:
  stage: review
  when: manual
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  script:
    - okteto preview destroy review-$CI_COMMIT_REF_SLUG
  variables:
    GIT_STRATEGY: none
  only:
    - branches
  except:
    - master
info

There are two different scopes for preview environments:

  • personal, where the only one who has access to the environment is the own user; and
  • global, where all cluster members have access.

This example creates a preview environment with global scope and requires administrator permissions using admin access tokens. To follow this example as a non-admin, use a Personal Access Token

A few recommendations when creating your preview environment:

  • Create a preview environment per branch/merge request to keep things isolated. We use a preview and $CI_COMMIT_REF_SLUG in the name to ensure the namespace is unique and that we only create one per branch.
  • Pass the URL of your preview environment using the environment.url key. That way, the reviewers can directly go to the preview environment from GitLab.
  • Delete both the preview environment, and the namespace when the branch is deleted to cut down on manual deletion.
tip

Learn more about the okteto CLI here.

Step 3: Create a Merge Request​

Once your changes are in your repository, make a small code change and create a new merge request.

After a few seconds, the workflow will update the pull request with the URL of your preview environment. Click on the View App button, access it, and see your changes running.

GitLab merge request

Step 4: Cleanup​

Merging the merge request or deleting the branch automatically triggers the stop-review job we defined in the .gitlab-ci.yml file. The stop-review job will destroy the preview environment automatically for you.