Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gatling/gatling.io-doc/llms.txt

Use this file to discover all available pages before exploring further.

Integrating performance testing into your GitLab CI/CD pipeline ensures that every code change is validated against your performance requirements before it reaches production. With Gatling Enterprise Edition and the official GitLab runner image, you can trigger a simulation, block the pipeline on its result, and surface pass/fail outcomes directly in merge request pipelines — without writing custom shell scripts.
Running simulations from GitLab CI/CD requires a Gatling Enterprise Edition account. Explore plans if you don’t have one yet.

​
Prerequisites

  • Gatling version 3.13 or higher
  • A Gatling Enterprise Edition account
  • The sample project from gatling/devrel-projects — navigate to articles/gitlabintegration

​
Step 1: Write the Simulation

Create a simple scenario that exercises your application. The example below targets an e-commerce demo site and checks that at least 90% of requests succeed. 
import {
  simulation,
  scenario,
  exec,
  rampUsers,
  global,
} from "@gatling.io/core";
import { http } from "@gatling.io/http";

export default simulation((setUp) => {
  const httpProtocol = http
    .baseUrl("https://ecomm.gatling.io")
    .acceptHeader("text/html,application/xhtml+xml");

  const browse = scenario("Browse Homepage").exec(
    http("Home Page").get("/")
  );

  setUp(
    browse.injectOpen(rampUsers(1).during(5))
  )
    .protocols(httpProtocol)
    .assertions(
      global().successfulRequests().percent().gt(90.0)
    );
});

​
Step 2: Deploy to Gatling Enterprise Edition

1

Generate an API token

In Gatling Enterprise Edition, navigate to API Tokens and create a token with at minimum the Configure permission.
2

Deploy your simulation package

Set the token in your environment and run the deploy command:
export GATLING_ENTERPRISE_API_TOKEN=<your-token>

# Maven
mvn gatling:enterpriseDeploy

# Gradle
gradle gatlingEnterpriseDeploy

# JavaScript CLI
npx gatling enterprise-deploy
3

Create a simulation in the UI

In Simulations, click Create New, select your package, configure load generator locations and sizes, then save.
4

Copy your simulation ID

Click the ⋮ menu beside your simulation and copy the Simulation ID (format: test_00000000000000000000000000).

​
Step 3: Store the API Token in GitLab CI/CD Variables

1

Open CI/CD settings

In your GitLab project, go to Settings → CI/CD and expand the Variables section.
2

Add the token variable

Click Add variable, set Visibility to Masked and hidden, enter GATLING_ENTERPRISE_API_TOKEN as the key, and paste your API token as the value.
Always use Masked and hidden visibility for your API token. This prevents the token from appearing in job logs even if a job explicitly echoes all environment variables.

​
Step 4: Configure the GitLab Pipeline

Add the following .gitlab-ci.yml to the root of your repository. The pipeline uses the official gatlingcorp/enterprise-runner Docker image which includes the gatlingEnterpriseStart command. 
# .gitlab-ci.yml
stages:
  - load-test

run-gatling-enterprise:
  stage: load-test
  image:
    name: gatlingcorp/enterprise-runner:1
    entrypoint: ['']
  script:
    - gatlingEnterpriseStart
  variables:
    # GATLING_ENTERPRISE_API_TOKEN is set in CI/CD Variables (masked)
    SIMULATION_ID: 'test_00000000000000000000000000'
Replace test_00000000000000000000000000 with the simulation ID you copied earlier.

​
Optional: Trigger from Merge Requests

To run load tests automatically when a merge request targets main, add a rule: 
run-gatling-enterprise:
  stage: load-test
  image:
    name: gatlingcorp/enterprise-runner:1
    entrypoint: ['']
  script:
    - gatlingEnterpriseStart
  variables:
    SIMULATION_ID: 'test_00000000000000000000000000'
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'

​
Optional: Pass Extra Parameters to the Simulation

Use EXTRA_ENV_VARS to forward CI pipeline variables (branch name, commit SHA, environment) into the Gatling simulation for tagging and reporting purposes. 
variables:
  SIMULATION_ID: 'test_00000000000000000000000000'
  EXTRA_ENV_VARS: 'GIT_BRANCH=$CI_COMMIT_REF_NAME,GIT_SHA=$CI_COMMIT_SHA'

​
Step 5: Run the Pipeline

Once the .gitlab-ci.yml is committed, push a change or trigger the pipeline manually from CI/CD → Pipelines → Run pipeline. The job log streams the simulation status and prints a direct link to the live Gatling Enterprise Edition report. The job exits with a non-zero code if the simulation’s assertions fail, blocking any downstream deployment jobs.

​
Pipeline Architecture Diagram

┌────────────────────────────────────────────────────────────────┐
│  GitLab CI/CD Pipeline                                         │
│                                                                │
│  build  ──►  test  ──►  load-test  ──►  deploy                │
│                         │                                      │
│                         │ gatlingEnterpriseStart               │
│                         ▼                                      │
│                  Gatling Enterprise Edition                     │
│                  (runs simulation, evaluates assertions)        │
│                         │                                      │
│                         ▼                                      │
│              ✅ Pass → pipeline continues                       │
│              ❌ Fail → pipeline blocked                         │
└────────────────────────────────────────────────────────────────┘

​
Key Benefits

  • No custom scripts — the enterprise-runner image handles authentication, simulation start, and polling.
  • Assertion-driven gates — your performance requirements are enforced as code, not manual review.
  • Unified history — every pipeline run is recorded in Gatling Enterprise Edition, enabling trend analysis across releases.

Build docs developers (and LLMs) love

Get started for freeTalk to us