> ## Documentation Index
> Fetch the complete documentation index at: https://checkly-422f444a-mintlify-fcc5020f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrating Checkly in GitLab CI/CD

> Run and deploy Checkly checks from a GitLab CI/CD pipeline, using a branch-aware setup that only promotes checks to monitors after they pass against production.

## Prerequisites

Before adding the pipeline, set the required credentials as GitLab CI/CD variables. In your GitLab project, go to **Settings > CI/CD > Variables** and add:

* `CHECKLY_API_KEY`: a Checkly API key, created on the [API keys tab](https://app.checklyhq.com/settings/user/api-keys) in your Checkly user settings. Mark this variable as **Masked** so it does not appear in job logs.
* `CHECKLY_ACCOUNT_ID`: your Checkly account ID, found on the [Account settings tab](https://app.checklyhq.com/settings/account/general).

The `variables` block in the pipeline example below references these CI/CD variables and exports them to the `checkly test` and `checkly deploy` commands.

## A Basic GitLab Pipeline Example

Create a new `.gitlab-ci.yml` file in your repo, or add the steps and stages from the example below to your existing file.
This pipeline is "branch aware" and treats the `main` branch as the production branch. This means checks are only deployed
to Checkly after they are ran against production (after merging to `main`) and the checks passed.

```yml .gitlab-ci.yml theme={null}
image: node:latest

# define your stages to deploy your app, run tests and then deploy the tests as monitors.
stages:
  - deploy
  - checkly-test
  - checkly-deploy

# Set the necessary credentials and export variables we can use to instrument our test run. Use the ENVIRONMENT_URL
# to run your checks against staging, preview or production.
variables:
  CHECKLY_API_KEY: "$CHECKLY_API_KEY"
  CHECKLY_ACCOUNT_ID: "$CHECKLY_ACCOUNT_ID"
  CHECKLY_TEST_REPO_BRANCH: "$CI_COMMIT_BRANCH"
  CHECKLY_TEST_REPO_URL:  "$CI_PROJECT_URL"

deploy-app:
  stage: deploy
  script:
    - echo "add your deployment logic here"
    # - ENVIRONMENT_URL= <add some command to extract a branch specific url to target

# Set a different environment name based on the branch you are testing against.
e2e-staging:
  stage: checkly-test
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules  
  variables:
    CHECKLY_TEST_ENVIRONMENT: review/$CI_COMMIT_REF_SLUG
  script:
    - npm ci
    - npx checkly test
  except:
    - main

e2e-production:
  stage: checkly-test
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules  
  variables:
    CHECKLY_TEST_ENVIRONMENT: "production"
  script:
    - npm ci
    - npx checkly test
  only:
    - main

monitor:
  stage: checkly-deploy
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules  
  needs: ["e2e-production"]
  script:
    - npx checkly deploy --force
  only:
    - main
```

The above example creates three stages:

* **deploy**: this is where your application specific deployment logic happens
* **checkly-test**: after the deploy stage, we run the `checkly test` command. We run two different jobs based on whether
  we are on the `main` branch of a different, feature branch so we can set a different environment.
* **checkly-deploy**: the last stage, that only runs on `main` is to deploy the checks to Checkly. Note that this stage
  only runs when the previous `e2e-production` job is successful.

The output in the GitLab CI CI/CD -> Pipelines tab will now look similar to this:

<img src="https://mintcdn.com/checkly-422f444a-mintlify-fcc5020f/1Pf3HM6D67CC05N1/images/docs/images/cicd/gitlab_ci_pipeline.png?fit=max&auto=format&n=1Pf3HM6D67CC05N1&q=85&s=4af15e8b282db3a295df8566d9e0e27b" alt="GitLab CI Pipeline" width="1093" height="583" data-path="images/docs/images/cicd/gitlab_ci_pipeline.png" />