Integrate Gatling with Github Actions
Set up automated performance testing in your CI/CD pipeline using Gatling and GitHub Actions
At Gatling, we strongly believe the shift-left approach is fundamental to ensuring application quality. This methodology, which involves integrating testing as early as possible in the development cycle, is particularly crucial for performance testing. Detecting and resolving performance issues before production deployment helps prevent critical and costly situations.
In this guide, we demonstrate how to integrate performance testing into your CI/CD pipeline using Gatling and GitHub Actions. This approach enables you to automate your performance tests and ensure application reliability.
Prerequisites
- Gatling version
3.13.5
or higher - An account on Gatling Entreprise
- Clone this code and cd into the
articles/githubintegration
folder.
Test Creation
Create the Scenario
In this tutorial, we create a small scenario using our JS SDK. Our users will load the home page of our e-commerce website demo.
import {
simulation,
scenario,
atOnceUsers,
global,
} from "@gatling.io/core";
import { http } from "@gatling.io/http";
export default simulation((setUp) => {
const httpProtocol = http
.baseUrl("https://ecomm.gatling.io")
const GetHome = scenario("Ecommerce").exec(
http("Get home").get("/")
);
import static io.gatling.javaapi.core.CoreDsl.*;
import static io.gatling.javaapi.http.HttpDsl.*;
import io.gatling.javaapi.core.*;
import io.gatling.javaapi.http.*;
public class EcommerceGithubActionSampleJava extends Simulation {
HttpProtocolBuilder httpProtocol =
http.baseUrl("https://ecomm.gatling.io")
.acceptHeader("application/json")
.contentTypeHeader("application/json");
ScenarioBuilder GetHome = scenario("Ecommerce")
.exec(http("Get home")
.get("/"));
import io.gatling.core.scenario.Simulation
import io.gatling.core.Predef._
import io.gatling.http.Predef._
class EcommerceGithubActionSampleScala extends Simulation {
val httpProtocol = http
.baseUrl("https://ecomm.gatling.io")
.acceptHeader("application/json")
.contentTypeHeader("application/json")
val GetHome = scenario("Ecommerce")
.exec(http("Get home").get("/"))
import io.gatling.javaapi.core.*
import io.gatling.javaapi.http.*
import io.gatling.javaapi.core.CoreDsl.*
import io.gatling.javaapi.http.HttpDsl.*
class EcommerceGithubActionSampleKotlin : Simulation() {
val httpProtocol = http
.baseUrl("https://ecomm.gatling.io")
.acceptHeader("application/json")
.contentTypeHeader("application/json")
val GetHome = scenario("Ecommerce")
.exec(http("Get home").get("/"))
Generate the user and assertions
In our example, we generate 1 user coming at once to see if our simulation is working. After that, we define our assertions, which allows us to assert the maximum or minimum response time, the percentage of successful requests, and more. In our case, we only check if we have more than 90% successful requests.
setUp(
GetHome.injectOpen(atOnceUsers(1)),
).assertions(
global().successfulRequests().percent().gt(90.0)
).protocols(httpProtocol);
{
setUp(
GetHome.injectOpen(atOnceUsers(1))
).assertions(
global().successfulRequests().percent().gt(90.0)
).protocols(httpProtocol);
}
setUp(
GetHome.inject(atOnceUsers(1))
).assertions(
global.successfulRequests.percent.gt(90.0)
).protocols(httpProtocol)
init {
setUp(
GetHome.injectOpen(atOnceUsers(1))
).assertions(
global().successfulRequests().percent().gt(90.0)
).protocols(httpProtocol)
}
Gatling Enterprise
Deploy to Gatling Enterprise
Now that we have our test locally, we need to deploy the package to Gatling Enterprise to create a simulation.
Create the Simulation
Now that our package is on Gatling Enterprise, we need to create a simulation.
Copy Your Simulation ID
Don’t forget to copy your simulation Id
(click on the three dots to the right of your simulation name); we will need it later.
Create an API Key
Now, for GitHub to communicate with Gatling Enterprise and launch the simulation, you need to create an API key.
Now that everything is set up on the Gatling Enterprise side, it’s time to create our CI script on GitHub.
GitHub Actions
Set up the Secrets and Environment
To successfully launch our workflow, we begin by configuring a secret in our GitHub repository. This secret is essential for securely managing access to external services and APIs. To add the secret, follow these steps:
- Navigate to your GitHub repository
- Go to the “Settings” tab
- In the left sidebar, click “Secrets and variables”
- Select “Actions”
- Click on the “New repository secret” button
- Add a new secret named
GATLING_ENTERPRISE_API_TOKEN
- Set the value of this secret to your API token
If you don’t have an API token yet, you can learn how to create one by following the instructions on this page
Understand the Workflow
Now, let’s create a simple workflow. This workflow, when launched, prompts for a simulation Id
and runs the specified simulation.
Below is the configuration for the workflow:
/*
* Copyright 2011-2025 GatlingCorp (https://gatling.io)
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
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 }}
If you wish to customize this workflow further, refer to our GitHub documentation for more details and options.
Launch the Workflow
Now that our requirements are set up, go to GitHub → Actions and launch our workflow with the simulation Id
as an input. After that, you will have a link to check the results on Gatling Enterprise and see logs in the workflow.
Conclusion
Integrating Gatling with GitHub Actions offers a solution for automating performance testing. By adopting this shift-left approach, you can identify and address performance issues early in the development cycle, ensuring higher application quality and reliability.
This integration streamlines the testing process and enhances efficiency between development teams. With Gatling Enterprise and GitHub Actions, you can create a workflow that monitors your application’s performance