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.

The Gatling Enterprise Jenkins plugin connects your Jenkins CI instance directly to Gatling Enterprise Edition, enabling you to start a simulation from a Pipeline step or a classic freestyle build step. The plugin streams live metrics to the build console and can publish assertion results as JUnit test reports so they appear natively in the Jenkins UI.
This integration is only available on Gatling Enterprise Edition. The plugin starts pre-configured simulations — create them first in the Gatling Enterprise Edition dashboard.

​
Installation

1

Download the Plugin

Download the .hpi file from the Gatling Enterprise CI plugins releases page.
2

Install in Jenkins

Log in as a Jenkins administrator. Navigate to Manage Jenkins → Manage Plugins → Advanced Settings → Deploy Plugin. Either upload the .hpi file or paste the download URL into the URL field, then click Deploy.
3

Restart Jenkins

Restart Jenkins to activate the plugin.

​
API Token and Credentials

The plugin requires a Gatling Enterprise Edition API token with the Start permission. Store it securely using Jenkins credentials:
1

Open Credentials Manager

Navigate to Manage Jenkins → Manage Credentials. You will see your existing credential stores.
2

Add a New Credential

Click on your target domain, then Add Credentials. Choose Secret text as the type, paste your API token in the Secret field, enter a meaningful ID (e.g., GATLING_API_TOKEN), and click Create.
You can configure an API token directly in the global plugin settings instead of using Jenkins credentials, but this approach is less secure and not recommended.

​
Global Configuration

Navigate to Manage Jenkins → Configure System → Global Gatling Enterprise Plugin Configuration and:
  • Select the Jenkins credential containing your API token.
  • Set Address to https://cloud.gatling.io.
  • Set API Address to https://api.gatling.io (or leave blank to use the default when Address is https://cloud.gatling.io).
If you route API traffic through an internal gateway, specify that gateway’s URL as the API Address.

​
Pipeline Configuration

Use the Pipeline Syntax generator in Jenkins to build your step configuration: click Pipeline Syntax, select the gatlingEnterpriseLauncherStep step, choose a simulation, and click Generate Groovy.

​
Declarative Pipeline

pipeline {
    agent any
    stages {
        stage("Gatling Enterprise simulation") {
            steps {
                gatlingEnterpriseLauncherStep simulationId: '00eacd1c-ef91-4076-ad57-99b4c6675a9e'
            }
        }
    }
}

​
Scripted Pipeline

node {
    stage("Gatling Enterprise simulation") {
        gatlingEnterpriseLauncherStep simulationId: '00eacd1c-ef91-4076-ad57-99b4c6675a9e'
    }
}

​
Overriding Global Configuration

Override the globally configured URLs or API token for individual steps — useful when migrating simulations from self-hosted to cloud, or when using per-team API tokens: 
gatlingEnterpriseLauncherStep(
    simulationId: '00eacd1c-ef91-4076-ad57-99b4c6675a9e',
    credentialId: 'GATLING_API_TOKEN',
    address: 'https://cloud.gatling.io',
    apiAddress: 'https://api.gatling.io'
)

​
Passing System Properties

Pass custom Java system properties to the Gatling Enterprise Edition run: 
gatlingEnterpriseLauncherStep(
    simulationId: '00eacd1c-ef91-4076-ad57-99b4c6675a9e',
    systemProps: [
        "var": "$var1",
        "sensitive.var2": "this prop won't be displayed in the run snapshot"
    ]
)

​
Configuring Run Status Logs

Control how frequently live status summaries are printed to the build log: 
gatlingEnterpriseLauncherStep(
    simulationId: '00eacd1c-ef91-4076-ad57-99b4c6675a9e',
    runSummaryEnabled: true,
    runSummaryInitialRefreshInterval: 5,
    runSummaryInitialRefreshCount: 12,
    runSummaryRefreshInterval: 60
)
By default, summaries are logged every 5 seconds for the first 60 seconds, then every 60 seconds thereafter.

​
Publishing Assertions as JUnit

Add the JUnit publisher step after the Gatling step to display assertion results as test cases: 
pipeline {
    agent any
    stages {
        stage("Load Test") {
            steps {
                gatlingEnterpriseLauncherStep simulationId: '00eacd1c-ef91-4076-ad57-99b4c6675a9e'
            }
        }
    }
    post {
        always {
            junit "gatlingEnterpriseJunitResults/*.xml"
        }
    }
}
If your simulation has no assertions configured, the JUnit step will fail. Only add it when your simulation includes at least one assertion.

​
Freestyle Job Configuration

For non-Pipeline jobs:
1

Add Build Step

Add a build step called Gatling Enterprise Edition Plugin. Select the simulation from the drop-down list.
2

Configure API Token (Optional)

If you don’t want to use the globally configured token, select a different Jenkins secret text credential.
3

Add JUnit Publisher (Optional)

Add a post-build action Publish JUnit test result report with the test report path set to gatlingEnterpriseJunitResults/*.xml.

​
Usage

Every time a job runs, the plugin starts a new Gatling Enterprise Edition simulation run. Live metrics appear in the Console Output, and a View Run in Gatling Enterprise Edition link in the build page menu links directly to the run dashboard.

Build docs developers (and LLMs) love

Get started for freeTalk to us