You can integrate mabl with your GitLab CI/CD pipelines easily using mabl's prebuilt GitLab pipeline images.

The GitLab pipeline integration lets you:

• Easily trigger mabl tests from your CI/CD pipeline
• See mabl test result summaries as a pipeline stage
• Review mabl test results in merge requests

📘

Should I use the GitLab Integration or mabl-cli image?

This integration is meant to automatically add mabl test result information to your GitLab Merge Requests, and easily integration with GitLab CI/CD Pipelines. If, however, you want to use all the possible features of the mabl test triggering APIs, consider using the Mabl CLI Docker image, or install the mabl CLI overview directly in your Pipeline.

Setup

Add mabl to your pipeline

You will need to add the following pipeline stage to your .gitlab-ci.yml in the pipeline you wish to run mabl tests. The operative section is the run-mabl-tests section below:

📘

Tying build success to mabl test success

The mabl build stage will emit a non-zero exit code when mabl tests fail. This will trigger your pipeline to be marked as "failed" in GitLab. To avoid this, set the MABL_FAIL_STAGE_ON_TEST_FAIL='false' in your stage variables.

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"

You can customize the action taken by the integration by test selector flags from the mabl CLI deployments create command in the MABL_TEST_SELECTORS environment variable, including:

• --application-id to choose an application to test
• --environment-id to choose an environment to test
• --labels to run plans that match any supplied label
• --url to pass a URL override for test execution

Note: either --application-id or --environment-id must be passed

📘

Working with Preview Environments / Review Apps

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

Create a personal access token for mabl

You need to create an api scoped Personal Access Token so that mabl can update your merge requests. To do this, visit the Personal Access Tokens section of GitLab and create a key called Mabl Access Token, as pictured below.

Be sure to save the token value.

Create a mabl API key for GitLab

You can find your mabl API access key in mabl under Settings > API. If you don't already have a CLI scoped key, see the Advanced API Key Management documentation for how to create and manage keys.

Add the necessary secrets to your project

You need to save the necessary secrets to the project your CI/CD pipeline will run under.

1. Visit Project > Settings > CI/CD > Variables
2. Add the variable MABL_GITLAB_API_TOKEN and set it to the personal access token created above.
3. Add the variable MABL_REST_API_KEY and set it to your mabl API key.

Unless you are using Protected Branches/Tags (learn more), uncheck the Protected option.

Mabl Auto-branching Support

It's often useful to run feature branch tests on a branch of mabl tests. By default, the GitLab integration will detect your GitLab build branch, and (1) automatically create a mabl test branch of the same name and (2) execute your mabl test run against that branch. This will only happen if mabl can detect your branch from GitLab supplied metadata.

This detected branch is visible in your mabl test results, as shown below.

Auto-branching support may be disabled by either

1. Passing --branch-name=your-preferred-name to the script variable MABL_TEST_SELECTORS
2. OR setting the script variable MABL_AUTO_BRANCH_ENABLED=false

You're All Done

Now, depending on the configuration of your GitLab CI/CD Pipeline, when your mabl tests stage runs, you'll be able to:

• See that the run started as a comment in your merge request
• See the live status of the running tests in your pipeline job page
• See the output of your tests in Markdown on your merge request when they finish
• Fail your build if your mabl tests fail (optional)

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