Gatling Enterprise GitLab CI/CD Pipeline Integration

Gatling Enterprise Edition provides an official Docker runner image — gatlingcorp/enterprise-runner — that integrates directly with GitLab CI/CD pipelines. You configure it as a job image, pass your simulation ID through environment variables, and the runner launches the simulation, streams real-time status logs, and writes run outputs to a dotenv artifact that downstream jobs can consume.

This integration is only available on Gatling Enterprise Edition. The runner does not create simulations — configure them first in the Gatling Enterprise Edition dashboard using a build tool plugin (Maven, Gradle, or sbt).

Docker Image Coordinates

The runner image is published to Docker Hub:

gatlingcorp/enterprise-runner:1

Check releases at github.com/gatling/enterprise-action/releases. Specify only the major version tag (currently 1) to receive automatic patch updates.

Prerequisites

Create an API Token

Generate a Gatling Enterprise Edition API token with the Start permission.

Store the Token in GitLab

In your GitLab project, navigate to Settings → CI/CD → Variables and add GATLING_ENTERPRISE_API_TOKEN. Enable Mask variable to prevent it from appearing in job logs.

Note your Simulation ID

Copy the simulation ID from the Simulations page in Gatling Enterprise Edition. It looks like test_00000000000000000000000000.

Quickstart

Create a .gitlab-ci.yml file in your repository root:

stages:
  - load-test

run-gatling-enterprise:
  stage: load-test
  image:
    name: gatlingcorp/enterprise-runner:1
    entrypoint: ['']
  script:
    - gatlingEnterpriseStart
  variables:
    # GATLING_ENTERPRISE_API_TOKEN should be set as a masked CI variable
    SIMULATION_ID: 'test_00000000000000000000000000'

Push this to GitLab. The pipeline runs on every new commit; you can also trigger it manually from the CI/CD menu.

Build, Deploy, and Run (Combined Pipeline)

This pattern builds and uploads the simulation on every push to main, then immediately runs it on Gatling Enterprise Edition.

Maven
Gradle

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

stages:
  - build
  - load-test

variables:
  SIMULATION_ID: 'test_00000000000000000000000000'

build-gatling-simulation:
  stage: build
  image: maven:3-openjdk-17-slim
  script:
    - mvn gatling:enterpriseDeploy -Dgatling.enterprise.validateSimulationId=$SIMULATION_ID

run-gatling-enterprise:
  stage: load-test
  image:
    name: gatlingcorp/enterprise-runner:1
    entrypoint: ['']
  script:
    - gatlingEnterpriseStart

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

stages:
  - build
  - load-test

variables:
  SIMULATION_ID: 'test_00000000000000000000000000'

build-gatling-simulation:
  stage: build
  image: gradle:8-jdk21
  script:
    - gradle gatlingEnterpriseDeploy -Dgatling.enterprise.validateSimulationId=$SIMULATION_ID

run-gatling-enterprise:
  stage: load-test
  image:
    name: gatlingcorp/enterprise-runner:1
    entrypoint: ['']
  script:
    - gatlingEnterpriseStart

Scheduled Run (Separate Pipelines)

Configure a pipeline schedule in GitLab to run simulations on a recurring basis, independently of code pushes:

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"

stages:
  - load-test

run-gatling-enterprise:
  stage: load-test
  image:
    name: gatlingcorp/enterprise-runner:1
    entrypoint: ['']
  script:
    - gatlingEnterpriseStart
  variables:
    SIMULATION_ID: 'test_00000000000000000000000000'

Configuration Reference

Inputs

All configuration is passed as environment variables:

run-gatling-enterprise:
  stage: load-test
  image:
    name: gatlingcorp/enterprise-runner:1
    entrypoint: ['']
  script:
    - gatlingEnterpriseStart
  variables:
    GATLING_ENTERPRISE_API_TOKEN: 'my-api-token'  # Use a masked CI variable instead!
    SIMULATION_ID: 'test_00000000000000000000000000'
    TITLE: 'My run title'
    DESCRIPTION: 'My run description'
    EXTRA_SYSTEM_PROPERTIES: >
      {
        "sys_prop_1": "value 1",
        "sys_prop_2": 42
      }
    EXTRA_ENVIRONMENT_VARIABLES: >
      {
        "ENV_VAR_1": "value 1"
      }
    FAIL_ACTION_ON_RUN_FAILURE: 'true'
    WAIT_FOR_RUN_END: 'true'
    RUN_SUMMARY_ENABLED: 'true'
    RUN_SUMMARY_INITIAL_REFRESH_INTERVAL: '5'
    RUN_SUMMARY_INITIAL_REFRESH_COUNT: '12'
    RUN_SUMMARY_REFRESH_INTERVAL: '60'

Variable	Required	Default	Description
`GATLING_ENTERPRISE_API_TOKEN`	Yes	—	API token for authenticating with Gatling Enterprise Edition.
`SIMULATION_ID`	Yes	—	The ID of the simulation to run.
`TITLE`	No	—	Title for the run report.
`DESCRIPTION`	No	—	Description for the run summary.
`EXTRA_SYSTEM_PROPERTIES`	No	—	JSON object of additional Java system properties.
`EXTRA_ENVIRONMENT_VARIABLES`	No	—	JSON object of additional environment variables.
`FAIL_ACTION_ON_RUN_FAILURE`	No	`true`	Fail the job if the simulation ends in error or failed assertions.
`WAIT_FOR_RUN_END`	No	`true`	Wait for the simulation to complete before the job finishes.
`OUTPUT_DOT_ENV_FILE_PATH`	No	`gatlingEnterprise.env`	Path to the dotenv output file.
`RUN_SUMMARY_ENABLED`	No	`true`	Log run status summaries to the console.
`RUN_SUMMARY_INITIAL_REFRESH_INTERVAL`	No	`5`	Seconds between early status logs.
`RUN_SUMMARY_INITIAL_REFRESH_COUNT`	No	`12`	Number of early log entries before switching to the slower interval.
`RUN_SUMMARY_REFRESH_INTERVAL`	No	`60`	Seconds between later status logs.

Outputs

The runner writes results to a dotenv file (default: gatlingEnterprise.env). Export it as an artifact to share values with downstream jobs:

stages:
  - load-test
  - post-load-test

run-gatling-enterprise:
  stage: load-test
  image:
    name: gatlingcorp/enterprise-runner:1
    entrypoint: ['']
  script:
    - gatlingEnterpriseStart
  variables:
    SIMULATION_ID: 'test_00000000000000000000000000'
  artifacts:
    reports:
      dotenv: 'gatlingEnterprise.env'

print-output:
  stage: post-load-test
  image: alpine:latest
  script: |
    echo "RUN_ID=$RUN_ID"
    echo "REPORTS_URL=$REPORTS_URL"
    echo "RUN_STATUS_NAME=$RUN_STATUS_NAME"
    echo "RUN_ASSERTIONS=$RUN_ASSERTIONS"

Variable	Description
`RUN_ID`	The ID of the started run.
`REPORTS_URL`	URL to the run’s report page in Gatling Enterprise Edition.
`RUNS_URL`	URL to the simulation’s run history page.
`RUN_STATUS_NAME`	Final run status (e.g., `Successful`, `AssertionsFailed`).
`RUN_STATUS_CODE`	Numeric code of the final run status.
`RUN_ASSERTIONS`	JSON array of assertion results.

Logs

The runner logs a status summary every few seconds during the run. By default, summaries appear every 5 seconds for the first minute, then every 60 seconds. Adjust or disable this with RUN_SUMMARY_* variables. When RUN_SUMMARY_ENABLED: 'false', only the final result is logged.

Build Tools

CI/CD Platforms

Observability & Notifications

Gatling Enterprise GitLab CI/CD Pipeline Integration

Docker Image Coordinates

Prerequisites

Quickstart

Build, Deploy, and Run (Combined Pipeline)

Scheduled Run (Separate Pipelines)

Configuration Reference

Inputs

Outputs

Logs

Build docs developers (and LLMs) love

Build Tools

CI/CD Platforms

Observability & Notifications

Documentation Index

​Docker Image Coordinates

​Prerequisites

​Quickstart

​Build, Deploy, and Run (Combined Pipeline)

​Scheduled Run (Separate Pipelines)

​Configuration Reference

​Inputs

​Outputs

​Logs

Build docs developers (and LLMs) love

Docker Image Coordinates

Prerequisites

Quickstart

Build, Deploy, and Run (Combined Pipeline)

Scheduled Run (Separate Pipelines)

Configuration Reference

Inputs

Outputs

Logs