Preview Environments with Gitlab

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


Step 1: Fork the Sample Repository

For this tutorial, we'll be using this application.

Step 2: 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 personal access token.
  2. OKTETO_USERNAME: your Okteto username (in Okteto Cloud, this is your Github Username).
  3. [Optional] OKTETO_URL: if you are using Okteto Enterprise, specify the URL of your instance of Okteto Enterprise (e.g.,

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.

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

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

  5. Repeat the same process to add the OKTETO_USERNAME and, for enterprise users, the OKTETO_URL variables.

Step 3: 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 Pipeline 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 Pipeline
  2. Delete the dedicated namespace

The .gitlab-ci.yml looks like this:

# file:
image: okteto/okteto:1.12.3
- review
stage: review
- okteto create namespace review-$CI_BUILD_REF_NAME-$OKTETO_USERNAME
- okteto pipeline deploy --repository $CI_REPOSITORY_URL --branch $CI_COMMIT_REF_NAME --namespace review-$CI_BUILD_REF_NAME-$OKTETO_USERNAME --wait
name: review/$CI_BUILD_REF_NAME
url: https://movies-review-$CI_BUILD_REF_NAME-$
on_stop: stop-review
- branches
- master
stage: review
when: manual
name: review/$CI_BUILD_REF_NAME
action: stop
- okteto pipeline destroy --namespace review-$CI_BUILD_REF_NAME-$OKTETO_USERNAME --wait
- okteto delete namespace review-$CI_BUILD_REF_NAME-$OKTETO_USERNAME
- branches
- master

A few recommendations when creating your preview environment:

  • Create a namespace per branch/merge request to keep things isolated. We use both $CI_BUILD_REF_NAME and $OKTETO_USERNAME 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.

Learn more about the okteto CLI here.

Step 4: 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.

Step 5: 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-reviewjob will destroy the pipeline and delete the namespace automatically for you.

Configure your Gitlab Runner in Okteto

Okteto makes it easy to deploy your own Gitlab Runner from the Okteto Catalog. Running your runners is useful if you find yourself constantly waiting for shared runners to be available or want to run more complex configurations.

Retrieve the Registration Information

  1. Navigate to your Gitlab repository.
  2. Go to the Settings menu on the left, and click on the CI/CD entry.

  3. Expand the Runners section, and copy the URL and registration tokens.

Deploy your Gitlab Runner

  1. Log into Okteto Cloud.
  2. Click on the Deploy button on the top.
  3. Click on the From Chart option on the left, select gitlab-runner from the options below, and click Deploy.

  4. On the configuration section, add your runner registration token to the runnerRegistrationToken key.

  5. [Optional] If you're running your own Gitlab instance, also update the value of gitlabUrl.
  6. Press the Deploy button.

In a few seconds, your Gitlab Runner will be deployed and registered with your repository. To validate this, go back to the Runners section on your repository's settings, and validate that the runner is available there.

To learn more about GitLab Runners, we recommend you check their official documentation.