Gitlab CI/CD

Run your Gatling Enterprise simulations from Gatling CI.

We do not yet offer a dedicated Docker image for Gitlab CI/CD, but you can easily run your simulations on Gatling Enterprise from GitLab CI/CD, using either one of the supported build tools or our CI shell script.

This will not create a new Gatling Enterprise simulation, you have to create it using the Gatling Enterprise Dashboard before, or do it using the options provided by our build tools plugins:

Pre-requisites

You must first create an API token. It will be used to authenticate with Gatling Enterprise. You can store the API Token in a Gitlab CI Variable (make sure to check “Mask variable”) with the name GATLING_ENTERPRISE_API_TOKEN. Or if you use a vault to store secrets, store the API Token in your vault and retrieve its value to an environment variable named GATLING_ENTERPRISE_API_TOKEN in your Gitlab CI/CD configuration file.

In the following examples, we assume the API Token is available in an environment variable named GATLING_ENTERPRISE_API_TOKEN, which our tools will detect automatically.

We also assume that you have already configured a simulation on Gatling Enterprise. You can copy the simulation ID from the simulations list view. In the following examples, we will show the simulation ID as 00000000-0000-0000-0000-000000000000.

Using a build tool plugin

You can build you Simulation, and then run the updated Simulation on Gatling Enterprise, using the enterpriseRun command with any of our supported build tools.

With the waitForRunEnd=true option, it will display live metrics until the end of the run, and exit with an error code if the run fails on Gatling Enterprise (e.g. if the run crashes or if the assertions fail).

Configure your CI build to run the command corresponding to the build tool you use. Here are some examples:

# Gradle 8 and JDK 17; see https://hub.docker.com/_/gradle for other tags available
image: gradle:8-jdk17

stages:
  - run-gatling-enterprise

run-gatling-enterprise:
  stage: run-gatling-enterprise
  script:
    # See all options on https://gatling.io/docs/gatling/reference/current/extensions/gradle_plugin/#working-with-gatling-enterprise-cloud
    - gradle gatlingEnterpriseStart
      -Dgatling.enterprise.simulationId=00000000-0000-0000-0000-000000000000
      -Dgatling.enterprise.waitForRunEnd=true

# See also https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Gradle.gitlab-ci.yml
# for other useful options for Gradle builds.

# Gradle 8 and JDK 17; see https://hub.docker.com/_/gradle for other tags available
image: azul/zulu-openjdk:17-latest

stages:
  - run-gatling-enterprise

run-gatling-enterprise:
  stage: run-gatling-enterprise
  script:
    # See all options on https://gatling.io/docs/gatling/reference/current/extensions/gradle_plugin/#working-with-gatling-enterprise-cloud
    - ./gradlew gatlingEnterpriseStart
      -Dgatling.enterprise.simulationId=00000000-0000-0000-0000-000000000000
      -Dgatling.enterprise.waitForRunEnd=true

# See also https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Gradle.gitlab-ci.yml
# for other useful options for Gradle builds.

# Maven 3 and JDK 17; see https://hub.docker.com/_/maven for other tags available
image: maven:3-openjdk-17-slim

stages:
  - run-gatling-enterprise

run-gatling-enterprise:
  stage: run-gatling-enterprise
  script:
    # See all options on https://gatling.io/docs/gatling/reference/current/extensions/maven_plugin/#working-with-gatling-enterprise-cloud
    - mvn --batch-mode gatling:enterpriseStart
      -Dgatling.enterprise.simulationId=00000000-0000-0000-0000-000000000000
      -Dgatling.enterprise.waitForRunEnd=true

# See also https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Maven.gitlab-ci.yml
# for other useful options for Maven builds.

# SBT 1.8.2 and JDK 17.0.5; sbtscala/scala-sbt does not provide 'latest' tags
# See https://hub.docker.com/r/sbtscala/scala-sbt for other tags available and for the latest versions
image: sbtscala/scala-sbt:eclipse-temurin-17.0.5_8_1.8.2_2.13.10

stages:
  - run-gatling-enterprise

run-gatling-enterprise:
  stage: run-gatling-enterprise
  script:
    # See all options on https://gatling.io/docs/gatling/reference/current/extensions/sbt_plugin/#working-with-gatling-enterprise-cloud
    - sbt Gatling/enterpriseStart
      -Dgatling.enterprise.simulationId=00000000-0000-0000-0000-000000000000
      -Dgatling.enterprise.waitForRunEnd=true

Using a shell script

This script launches an existing simulation on Gatling Enterprise and displays live metrics.

It can be downloaded here.

Shell script requirements

This script runs with:

These tools must be installed on the machine or container where your CI system will execute the script.

Shell script usage

You need to give 3 parameters to the script:

  • Gatling Enterprise url: https://cloud.gatling.io.
  • API token: the API token will allow the script to authenticate to Gatling Enterprise. The API token needs the Start permission.
  • Simulation ID: the ID of the simulation you want to start. You can get this ID on the Simulations table, with the icon.

Configure your CI build to call the script, for example::

image: ubuntu:latest

stages:
  - run-gatling-enterprise

run-gatling-enterprise:
  stage: run-gatling-enterprise
  script:
    # Assuming the script is present at the root of the repository
    - ./start_simulation.sh 'https://cloud.gatling.io' "$GATLING_ENTERPRISE_API_TOKEN" '00000000-0000-0000-0000-000000000000'

Edit this page on GitHub

← GitHub Actions
Jenkins Plugin →