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-action GitHub Action lets you start a Gatling Enterprise Edition simulation directly from any GitHub Actions workflow. It connects a workflow job to a single pre-configured simulation and streams run status to the Actions console until the run completes. Failed assertions can automatically fail the workflow, making it easy to enforce performance budgets in your CI/CD pipeline.
This integration is only available on Gatling Enterprise Edition. The Action does not create simulations — you must first configure them in the Gatling Enterprise Edition dashboard using one of the build tool plugins (Maven, Gradle, or sbt). Action Coordinates
The Action is published at: gatling/enterprise-action@v1
Check the latest releases at github.com/gatling/enterprise-action/releases. You generally only need to specify the major version (currently v1).
Prerequisites
Create an API Token
Generate a Gatling Enterprise Edition API token with the Start permission. This token authenticates the Action with the platform.
Store the Token as a GitHub Secret
In your repository settings, add an encrypted secret named GATLING_ENTERPRISE_API_TOKEN. Note your Simulation ID
Copy the simulation ID from the Simulations list view in Gatling Enterprise Edition. It looks like test_00000000000000000000000000.
Quickstart
The following minimal workflow triggers a simulation manually using workflow_dispatch:
name: Run Gatling Enterprise Simulation
on:
workflow_dispatch:
inputs:
simulation_id:
type: string
required: true
jobs:
run:
runs-on: ubuntu-latest
steps:
- name: Gatling Enterprise Action
uses: gatling/enterprise-action@v1
with:
api_token: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}
simulation_id: ${{ inputs.simulation_id }}
workflow_dispatch trigger to appear in the Actions tab.
Build, Deploy, and Run (Combined Workflow)
This pattern builds and uploads the simulation on every push to main, then immediately runs it on Gatling Enterprise Edition.
name: Run Gatling Enterprise Simulation
on:
push:
branches:
- main
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
env:
SIMULATION_ID: 'test_00000000000000000000000000'
GATLING_ENTERPRISE_API_TOKEN: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}
jobs:
run:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup JDK
uses: actions/setup-java@v4
with:
distribution: 'zulu'
java-version: '21'
cache: 'maven'
- name: Build Gatling simulation
run: mvn gatling:enterpriseDeploy -Dgatling.enterprise.validateSimulationId=${{ env.SIMULATION_ID }}
- name: Gatling Enterprise Action
uses: gatling/enterprise-action@v1
with:
simulation_id: ${{ env.SIMULATION_ID }}
name: Run Gatling Enterprise Simulation
on:
push:
branches:
- main
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
env:
SIMULATION_ID: 'test_00000000000000000000000000'
GATLING_ENTERPRISE_API_TOKEN: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}
jobs:
run:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup JDK
uses: actions/setup-java@v4
with:
distribution: 'zulu'
java-version: '21'
cache: 'gradle'
- name: Build Gatling simulation
run: gradle gatlingEnterpriseDeploy -Dgatling.enterprise.validateSimulationId=${{ env.SIMULATION_ID }}
- name: Gatling Enterprise Action
uses: gatling/enterprise-action@v1
with:
simulation_id: ${{ env.SIMULATION_ID }}
name: Run Gatling Enterprise Simulation
on:
push:
branches:
- main
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
env:
SIMULATION_ID: 'test_00000000000000000000000000'
GATLING_ENTERPRISE_API_TOKEN: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}
jobs:
run:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup JDK
uses: actions/setup-java@v4
with:
distribution: 'zulu'
java-version: '21'
cache: 'sbt'
- name: Build Gatling simulation
run: sbt Gatling/enterpriseDeploy -Dgatling.enterprise.validateSimulationId=${{ env.SIMULATION_ID }}
- name: Gatling Enterprise Action
uses: gatling/enterprise-action@v1
with:
simulation_id: ${{ env.SIMULATION_ID }}
Scheduled Weekly Run
Separate your build and run workflows to update the simulation on every push and run it on a schedule:
name: Run Gatling Enterprise Simulation
on:
schedule:
- cron: '0 2 * * 0' # Every Sunday at 02:00 UTC
jobs:
run:
runs-on: ubuntu-latest
steps:
- name: Gatling Enterprise Action
uses: gatling/enterprise-action@v1
with:
api_token: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}
simulation_id: 'test_00000000000000000000000000'
Configuration Reference
The Action accepts the following inputs in the with: block:
steps:
- uses: gatling/enterprise-action@v1
with:
api_token: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}
simulation_id: 'test_00000000000000000000000000'
title: 'My run title'
description: 'My run description'
extra_system_properties: >
{
"sys_prop_1": "value 1",
"sys_prop_2": 42,
"sys_prop_3": true
}
extra_environment_variables: >
{
"ENV_VAR_1": "value 1",
"ENV_VAR_2": 42
}
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
| Input | Required | Default | Description |
|---|
api_token | Yes* | — | API token for authenticating with Gatling Enterprise Edition. Can also be set via the GATLING_ENTERPRISE_API_TOKEN env var. |
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 to merge with the simulation’s configured properties. |
extra_environment_variables | No | — | JSON object of additional environment variables. |
fail_action_on_run_failure | No | true | Fail the Action if the simulation ends in error or failed assertions. |
wait_for_run_end | No | true | Wait for the simulation to complete before the Action finishes. |
run_summary_enabled | No | true | Log a run status summary to the console periodically. |
run_summary_initial_refresh_interval | No | 5 | Seconds between early status log entries (rounded to multiples of 5). |
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 log entries. |
Outputs
Access run results in downstream steps using the step’s id:
steps:
- id: gatling-enterprise-action
uses: gatling/enterprise-action@v1
with:
api_token: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}
simulation_id: 'test_00000000000000000000000000'
- run: |
echo "run_id=${{ steps.gatling-enterprise-action.outputs.run_id }}"
echo "reports_url=${{ steps.gatling-enterprise-action.outputs.reports_url }}"
echo "run_status_name=${{ steps.gatling-enterprise-action.outputs.run_status_name }}"
echo "run_assertions=${{ steps.gatling-enterprise-action.outputs.run_assertions }}"
| Output | Description |
|---|
run_id | The ID of the started run. |
reports_url | URL to the run’s reports page in Gatling Enterprise Edition. |
runs_url | URL to the simulation’s runs 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. |
Cancellation
When the Action starts, it registers a post-execution cleanup task. If the workflow is cancelled while a simulation is running, the cleanup task will attempt to stop the simulation run on Gatling Enterprise Edition automatically.