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.

Shifting performance testing left means running load tests automatically on every pull request or deployment — not just before a release. GitHub Actions makes it straightforward to trigger a Gatling Enterprise simulation, block on the results, and fail the workflow if your defined assertions are not met. This guide walks through the full setup: creating a scenario, deploying it to Gatling Enterprise Edition, and wiring it into a GitHub Actions workflow.
Triggering simulations from GitHub Actions 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 cloned from gatling/devrel-projects — navigate to articles/githubintegration

​
Step 1: Write the Simulation

Create a scenario that exercises your target application. The example below uses the JavaScript SDK to simulate users loading an e-commerce homepage. 
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)
    );
});
The assertion — global().successfulRequests().percent().gt(90.0) — causes the workflow to fail if fewer than 90% of requests succeed.

​
Step 2: Deploy to Gatling Enterprise Edition

Before GitHub Actions can trigger a simulation, you must package and upload it to Gatling Enterprise Edition.
1

Generate an API token

In the Gatling Enterprise UI, go to API Tokens and create a token with the Configure permission. Keep it safe.
2

Set the token in your build tool

Export the token as GATLING_ENTERPRISE_API_TOKEN in your local shell, then run the deploy command:
# Maven
export GATLING_ENTERPRISE_API_TOKEN=<your-token>
mvn gatling:enterpriseDeploy

# Gradle
export GATLING_ENTERPRISE_API_TOKEN=<your-token>
gradle gatlingEnterpriseDeploy

# JavaScript CLI
export GATLING_ENTERPRISE_API_TOKEN=<your-token>
npx gatling enterprise-deploy
3

Create a simulation in the UI

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

Copy the simulation ID

Click the ⋮ menu next to your simulation name and copy the Simulation ID (format: test_00000000000000000000000000). You will use this in the workflow.

​
Step 3: Add the API Token to GitHub Secrets

1

Open repository settings

Navigate to your GitHub repository and click Settings.
2

Create the secret

Go to Secrets and variables → Actions, click New repository secret, name it GATLING_ENTERPRISE_API_TOKEN, and paste your token value.

​
Step 4: Create the GitHub Actions Workflow

Add a workflow file at .github/workflows/load-test.yml. The example below prompts for a simulation ID via workflow_dispatch inputs, making it easy to run on demand or from a CI event. 
# .github/workflows/load-test.yml
name: Gatling Load Test

on:
  workflow_dispatch:
    inputs:
      simulation_id:
        description: "Gatling Enterprise simulation ID"
        required: true
        type: string

jobs:
  load-test:
    runs-on: ubuntu-latest
    steps:
      - name: Run Gatling Enterprise Simulation
        uses: gatling/enterprise-action@v1
        with:
          api_token: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}
          simulation_id: ${{ inputs.simulation_id }}
To run load tests automatically on every push to main, replace the workflow_dispatch trigger with on: push: branches: [main] and hard-code the simulation_id in the with block.

​
Workflow Inputs and Action Parameters

ParameterDescription
api_tokenGatling Enterprise API token (use a GitHub secret)
simulation_idThe simulation ID from Gatling Enterprise
titleOptional display name for this run
descriptionOptional description for this run
extra_system_propertiesOptional JSON object of additional Java system properties (e.g. {"key": "value"})
extra_environment_variablesOptional JSON object of additional environment variables merged into the simulation
fail_action_on_run_failureSet to false to not fail the workflow if the simulation itself fails (default: true)
wait_for_run_endSet to false to start the simulation and exit without waiting for it to finish (default: true)

​
Step 5: Run the Workflow

1

Navigate to Actions

In your GitHub repository, click the Actions tab and select Gatling Load Test from the workflow list.
2

Run workflow

Click Run workflow, enter your Simulation ID, and click the green Run workflow button.
3

Monitor progress

GitHub Actions logs will stream the run status. A link to the Gatling Enterprise Edition live report is printed to the log as soon as the run starts.
4

Review results

When the run completes, the workflow step passes if all assertions pass and fails if any assertion is violated. Full metric details are available in the Gatling Enterprise Edition report.

​
What This Achieves

By integrating Gatling with GitHub Actions you:
  • Detect regressions automatically — a performance drop that breaks an assertion blocks the PR from merging.
  • Capture historical data — every simulation run is stored in Gatling Enterprise Edition, enabling trend analysis and run comparisons.
  • Keep tests close to code — the workflow YAML lives in the repository alongside the simulation, reviewed and versioned like any other code change.

Build docs developers (and LLMs) love

Get started for freeTalk to us