GitLab Integration
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.

See mabl results in your merge request

See mabl results live in your GitLab CI/CD 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 stagevariables
.
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 yourMABL_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 mabl's GitLab access token
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.

Create a mabl REST API key for use in GitLab
Add the necessary secrets to your project
You need to save the necessary secrets to the project your CI/CD pipeline will run under.
- Visit
Project > Settings > CI/CD > Variables
- Add the variable
MABL_GITLAB_API_TOKEN
and set it to the personal access token created above. - 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.

Add the mabl secrets to your GitLab project
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-detected branch named "your-branch" displayed in the mabl webapp
Auto-branching support may be disabled by either
- Passing
--branch-name=your-preferred-name
to the script variableMABL_TEST_SELECTORS
- 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
v1.0.6
- 23 July 2021- Added
MABL_AUTO_BRANCH_ENABLED
environment flag input, allowing disabling auto-branching support - Added
MABL_DEBUG_ENABLED
(set totrue
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
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
v1.0.4
- 18 July 2021- Dependency updates
- Optimizations
- mabl-cli version upgrade
v1.0.3
- 25 August 2020
v1.0.3
- 25 August 2020- Initial public release
Updated almost 2 years ago