Skip to main content

GitLab Integration

Eva Ferreira
  • Updated

Use the mabl GitLab integration to automatically trigger mabl plans associated with a specific mabl environment and/or application to run as a stage in your GitLab pipeline.

With the mabl GitLab pipeline image, you can:

  • Trigger mabl tests from your GitLab CI/CD pipeline
  • See mabl test result summaries as a pipeline stage
  • Review mabl test results in merge requests
Using the mabl-CLI image in your GitLab pipeline

The mabl GitLab pipeline image integrates with GitLab CI/CD pipelines and automatically adds mabl test result information to your GitLab Merge Requests.

However, if you want to use all the possible features of mabl deployment events, consider using the Mabl CLI Docker image or installing the mabl CLI directly in your Pipeline.

Add mabl to your pipeline

In the .gitlab-ci.yml file for your pipeline, add the run-mabl-tests stage shown in the following code block:

build-1:
stage: build
script:
    - echo "Building your code"
    - echo "Place your build code here"
# Add this build stage to your pipeline YAML
run-mabl-tests:
  image: mablhq/gitlab-integration:latest
  stage: test
  variables:
  # Use 'mabl deployments create --help' on @mablhq/mabl-cli to learn more about flags
  MABL_TEST_SELECTORS: "--application-id=<YOUR-APP-ID> --labels=gitlab-demo"
  script:
    - "./mabl/home/run.sh"
  only:
    - merge_requests
    - branches
  except:
    - main

deploy-1:
  stage: deploy
  script:
    - echo "Deploying code to production"
    - echo "Place your deployment code here"

The run-mabl-tests stage triggers a deployment event in mabl, which is a parallel run of all plans in a workspace that match the specified conditions, such as application, environment, and plan label.

Note

Only enabled plans configured to run on deployment are triggered by a deployment event. If a plan is disabled or lacks a deployment trigger, it does not run as part of a deployment event.

Use the MABL_TEST_SELECTORS variable to define which mabl tests you want to run.

  • At a minimum, you must include either --application-id or --environment-id. Learn more about obtaining IDs for mabl applications and environments here.
  • For a complete list of available arguments for the MABL_TEST_SELECTORS, see the options for the mabl deployments create command in the mabl CLI.

Auto-branching

By default, the GitLab integration detects your GitLab build branch, automatically creates a mabl test branch of the same name, and runs your mabl tests against that branch. The branch name appears in the mabl test results, as shown in the following image:

Auto-detected branch named "your-branch" displayed in the mabl webapp

Auto-detected branch named "your-branch" displayed in the mabl webapp

Note

Mabl can only create a new branch if it can detect the branch name from GitLab-supplied metadata.

To disable auto-branching support, take one of the following steps:

  • Pass --branch-name=your-preferred-name to the script variable MABL_TEST_SELECTORS
  • Set the script variable MABL_AUTO_BRANCH_ENABLED=false

Defining behavior on failure

By default, the mabl build stage emits a non-zero exit code when mabl tests fail. To prevent this behavior, add the MABL_FAIL_STAGE_ON_TEST_FAIL to your stage variables and set its value to false.

Working with review apps

If you are using GitLab Review Apps and Dynamic Environments, add the --url ${CI_ENVIRONMENT_URL} flag to the MABL_TEST_SELECTORS variable to test against your Review App.

Add CI/CD variables for your project

After configuring the run-mabl-tests stage in the .gitlab-ci.yml file, create the following variables:

  • In mabl, create a "CI/CD integration" API key from mabl. API key access is limited to workspace owners
  • In GitLab, create a personal access token called "Mabl Access Token"
Create mabl's GitLab access token

Create mabl's GitLab access token

Add the mabl API key and personal access token to the project that your CI/CD pipeline will run under:

  1. Visit Project > Settings > CI/CD > Variables
  2. Add the variable MABL_REST_API_KEY.
  3. Set MABL_REST_API_KEY to the value of your CI/CD Integration API key from mabl.
  4. Add the variable MABL_GITLAB_API_TOKEN.
  5. Set MABL_GITLAB_API_TOKEN to the value of the "Mabl Access Token" from GitLab.
  6. Unless you are using Protected Branches or Tags, uncheck the Protected option.
Add the mabl secrets to your GitLab project

Add the mabl secrets to your GitLab project

Results

Depending on the configuration of your GitLab CI/CD Pipeline, when the run-mabl-tests stage runs, you can:

  • See that the run started as a comment in your merge request
see-run-started.png
  • See the live status of running tests in your pipeline image
GitLab pipeline output
  • See the output of your tests in markdown on your merge request when they finish
  • Optionally fail your build if your mabl tests fail

Release notes

v1.0.6 - 23 July 2021

  • Added MABL_AUTO_BRANCH_ENABLED environment flag input, allowing disabling auto-branching support
  • Added MABL_DEBUG_ENABLED (set to true for debugging info)
  • Fixed bug where auto-branching combined with explicit branching caused failure to execute commands
  • Fixed bug where zero exit code could be emitted on failure
  • Added additional helpful logging to explain auto-branching support
  • Added additional error handling safeguards

v1.0.5 - 19 July 2021

  • Fixed bug where command would not execute of image default path had was altered

v1.0.4 - 18 July 2021

  • Dependency updates
  • Optimizations
  • mabl-cli version upgrade

v1.0.3 - 25 August 2020

  • Initial public release

Related articles