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:

1. Navigate to your GitHub repository
2. Go to the “Settings” tab
3. In the left sidebar, click “Secrets and variables”
4. Select “Actions”
5. Click on the “New repository secret” button
6. Add a new secret named GATLING_ENTERPRISE_API_TOKEN
7. 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

Edit this page on GitHub