GitLab CI browser testing
Run Monito after a GitLab deploy with an API key and the deployed URL. Includes an untested YAML example, URL handoff and protected-variable limits.
CI/CD · Checked 2026-10-23
Add a job after your review-app deployment and wait for Monito's browser verdict. The Monito CLI path works today; our team has not run this YAML in GitLab.
How it works
- Your review deploy job succeeds and passes its deployed URL through a dotenv artifact to the job that needs it.
- The Node job authenticates with MONITO_TOKEN and runs the project's saved tests against that URL with --base-url.
- The CLI waits and exits nonzero for failed or errored tests, failing the job. Inspect the browser evidence in Monito's run report.
Set it up
Pro or Team to create the API key used as MONITO_TOKEN. Browser runs use your credits. Plan details
- Create a Monito API key on Pro or Team. In GitLab Settings, CI/CD, Variables, store it as MONITO_TOKEN with masked visibility but not protected, because merge request pipelines from unprotected feature branches do not receive protected variables. Set MONITO_PROJECT_ID to your project ID.
- Have your existing review deploy job capture its deployed URL as DYNAMIC_ENVIRONMENT_URL in a dotenv file and publish it under artifacts:reports:dotenv. Keep credentials out of that artifact.
- Add the job below. Replace review with your deploy job's name and align both jobs' rules so the deploy job exists in each selected pipeline. The .post stage and needs dependency place the check after deployment.
- Enable GitLab's Pipelines must succeed merge check if failed pipelines should block merges. Keep allow_failure disabled for this job.
monito:
stage: .post
image: node:24
needs: [review]
script:
- test -n "$DYNAMIC_ENVIRONMENT_URL" || { echo "DYNAMIC_ENVIRONMENT_URL is empty"; exit 1; }
- npx -y @monitodev/cli@4 project run "$MONITO_PROJECT_ID" --wait --base-url "$DYNAMIC_ENVIRONMENT_URL"
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"Example our team has not run in GitLab. Add this job to a pipeline whose review job deploys the app and exports DYNAMIC_ENVIRONMENT_URL through a dotenv artifact. The guard fails the job if the URL is empty so the CLI cannot silently test the project's default environment instead of the review app. The image is pinned to node:24.
GitLab sources
The GitLab behavior and this example were checked against the following documentation on 2026-10-23. The benchmark reports below do not validate the GitLab configuration.
Example result
Example result: field names from the CLI, values illustrative
Selected fields from project run --wait --json. Each runs entry has its own id, status and sessionId. Add --json to read the full result. Open /session/<sessionId> on Monito, or follow the run report from the dashboard or GitHub summary to inspect browser evidence.
{
"runs": [
{
"id": "run_example",
"scenarioId": "scenario_example",
"status": "failed",
"sessionId": "session_example"
}
]
}Limits to account for
CI_ENVIRONMENT_URL is available only when that job has environment:url. A later job does not automatically inherit it. Use the dotenv variable as above, or repeat a static environment:name and environment:url with action: verify on the test job.
A protected MONITO_TOKEN does not reach merge request pipelines from ordinary unprotected feature branches. Making it unprotected allows those jobs to use it; masking does not stop malicious pipeline code from reading it. Review code before running a fork's pipeline in the parent project.
GitLab's default test stage precedes deploy. Use needs or a later stage to run against the newly deployed app.
A base-URL override preserves scenario paths and saved-login origin restrictions. It does not authorize credentials on a new preview origin.
Comparable benchmark runs
Our team published these runs in the reliability benchmark. They show comparable browser journeys, not executions of the configuration or illustrative result above. Run your own scenario before relying on this integration.