GitHub Actions

Run your Gatling Enterprise simulations from GitHub Actions.

Purpose of this GitHub Action

This Action enables you to start a Gatling Enterprise simulation directly from your GitHub Actions workflows. This plugin links a workflow with one and only one Gatling Enterprise simulation.

This plugin doesn’t create a new Gatling Enterprise simulation, you have to create it using the Gatling Enterprise Dashboard before, or do it using the options provided by our build tools plugins:

Don’t forget to check out GitHub’s official documentation to learn how to write CI/CD workflows with GitHub Actions.

Action coordinates

The Action is published with the following coordinates: gatling/enterprise-action@v1.

You can check out the latest releases available from the GitHub project. You generally only need to specify the major version you want to use, currently v1.

Pre-requisites

You must first create an API token, with at least the Start permission. It will be used by the Action to authenticate with Gatling Enterprise. We recommend storing the API Token in a GitHub encrypted secret. In the following examples, we assume the API Token is stored in a secret called GATLING_ENTERPRISE_API_TOKEN.

We also assume that you have already configured a simulation on Gatling Enterprise. You can copy the simulation ID from the simulations list view. In the following examples, we will show the simulation ID as 00000000-0000-0000-0000-000000000000.

Quickstart (minimal job configuration)

In this example, we configure a workflow which will only start a simulation as already configured and uploaded on Gatling Enterprise. We use the workflow_dispatch trigger event, so that we can run it manually, but feel free to use what works for your use case.

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 }}

Push this to your repository’s default branch (otherwise, new workflow_dispatch workflows don’t get detected). You can then run the workflow from you GitHub repository’s Actions tab. Select the workflow’s name from the menu on the left, and click on Run workflow.

Configuration reference

Several configuration options are available as Action inputs. This Action also provides several outputs which you can access in the following steps of your workflow.

Inputs

Example:

steps:
  - uses: gatling/enterprise-action@v1
    with:
      api_token: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}
      simulation_id: '00000000-0000-0000-0000-000000000000'
      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,
          "ENV_VAR_3":true
        }        
      override_load_generators: >
        {
          "4a399023-d443-3a58-864f-3919760df78b":{"size":1,"weight":60},
          "c800b6d9-163b-3db7-928f-86c1470a9542":{"size":1,"weight":40}
        }        
      fail_action_on_run_failure: true
      wait_for_run_end: true

api_token required (unless using an environment variable named GATLING_ENTERPRISE_API_TOKEN instead): The API token used by the Action to authenticate with Gatling Enterprise.
simulation_id required : The ID of the simulation as configured on Gatling Enterprise.
extra_system_properties optional : Additional Java system properties, will be merged with the simulation’s configured system properties. Must be formatted as a JSON object containing the desired key/value pairs. Values can be strings, numbers or booleans.
extra_environment_variables optional : Additional environment variables, will be merged with the simulation’s configured environment variables. Must be formatted as a JSON object containing the desired key/value pairs. Values can be strings, numbers or booleans.
override_load_generators optional : Overrides the simulation’s load generators configuration. Must be formatted as a JSON object. Keys are the load generator IDs, which can be retrieved from the public API (using the /pools route). Weights are optional.
fail_action_on_run_failure optional (defaults to true): If true, the Action will fail if the simulation run ends in an error (including failed assertions). Note: if set to false and the simulation ends in an error, some of the outputs may be missing (e.g. there will be no assertion results if the simulation crashed before the end).
wait_for_run_end optional (defaults to true): If true, the Action will wait for the end of te simulation run on Gatling Enterprise before terminating. Note: if set to false, some of the outputs may be missing (there will be no status nor assertion results).

Outputs

Example:

steps:
  - id: gatling-enterprise-action
    uses: gatling/enterprise-action@v1
    with:
      api_token: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}
      simulation_id: '00000000-0000-0000-0000-000000000000'
  - run: |
      echo "run_id=${{ steps.enterprise-action.outputs.run_id }}"
      echo "reports_url=${{ steps.enterprise-action.outputs.reports_url }}"
      echo "runs_url=${{ steps.enterprise-action.outputs.runs_url }}"
      echo "run_status_code=${{ steps.enterprise-action.outputs.run_status_code }}"
      echo "run_status_name=${{ steps.enterprise-action.outputs.run_status_name }}"
      echo "run_assertions=${{ steps.enterprise-action.outputs.run_assertions }}"

run_id: The ID of the run started by this action.
reports_url: The URL of the reports page for this run.
runs_url: The URL of the runs history page for this simulation.
run_status_name: The name of the run’s final status (e.g. Successful, AssertionsSuccessful, AssertionsFailed, etc.).
run_status_code: The code of the run’s final status.
run_assertions: The results of the run’s assertions, as a JSON array.

Logs

Every few seconds, the action logs to the GitHub Action console a summary of the run’s current status. When the run ends, the Action logs the status of the run and the results of any assertions. Here’s a very short duration example:

Cancellation

When the Action starts, it registers a post-execution, clean-up task in the workflow. If the Action fails or gets cancelled by a user, and if the simulation is still running on Gatling Enterprise, this clean-up task will attempt to cancel the execution on Gatling Enterprise.

Sample use cases

Build and run simulation

This workflow is defined in the GitHub repository which contains your Gatling simulation script built with one of our build tools plugins. In this example, every time the code on the main branch gets updated, we:

build, package, and upload to Gatling Enterprise the current version of the simulation script
run the updated simulation on Gatling Enterprise

Feel free to use different trigger events or to configure the other inputs and outputs for the Action as documented above, according to your own use case.

name: Run Gatling Enterprise Simulation

# Execute the workflow on each push to the main branch
on:
  push:
    branches:
      - main

# Here we use concurrency to cancel previous executions if they are still
# ongoing. Useful to avoid running the same simulation several times
# simultaneously if we push several code changes in a short time.
# See https://docs.github.com/actions/using-jobs/using-concurrency.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# The GATLING_ENTERPRISE_API_TOKEN environment variable is recognized by both
# the Gatling Gradle plugin and the gatling/enterprise-action Action
env:
  SIMULATION_ID: '00000000-0000-0000-0000-000000000000'
  GATLING_ENTERPRISE_API_TOKEN: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      # Check out your GitHub repository.
      - name: Checkout
        uses: actions/checkout@v3

      # Set up Java and the build tools (including Gradle).
      # You can configure other versions of the JDK, as long as they are
      # supported by your version of Gatling and by your build tool.
      # See https://github.com/actions/setup-java/blob/main/README.md for options.
      - name: Setup JDK
        uses: actions/setup-java@v3
        with:
          distribution: 'zulu'
          java-version: '17'
          cache: 'gradle'

      # Build, package, and upload your Gatling project 
      - name: Build Gatling simulation
        run: gradle gatlingEnterpriseUpload -Dgatling.enterprise.simulationId=${{ env.SIMULATION_ID }}

      # Run the simulation on Gatling Enterprise
      - name: Gatling Enterprise Action
        uses: gatling/enterprise-action@v1
        with:
          simulation_id: ${{ env.SIMULATION_ID }}

name: Run Gatling Enterprise Simulation

# Execute the workflow on each push to the main branch
on:
  push:
    branches:
      - main

# Here we use concurrency to cancel previous executions if they are still
# ongoing. Useful to avoid running the same simulation several times
# simultaneously if we push several code changes in a short time.
# See https://docs.github.com/actions/using-jobs/using-concurrency.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# The GATLING_ENTERPRISE_API_TOKEN environment variable is recognized by both
# the Gatling Gradle plugin and the gatling/enterprise-action Action
env:
  SIMULATION_ID: '00000000-0000-0000-0000-000000000000'
  GATLING_ENTERPRISE_API_TOKEN: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      # Check out your GitHub repository.
      - name: Checkout
        uses: actions/checkout@v3

      # Set up Java.
      # You can configure other versions of the JDK, as long as they are
      # supported by your version of Gatling and by your build tool.
      # See https://github.com/actions/setup-java/blob/main/README.md for options.
      - name: Setup JDK
        uses: actions/setup-java@v3
        with:
          distribution: 'zulu'
          java-version: '17'
          cache: 'gradle'

      # Build, package, and upload your Gatling project 
      - name: Build Gatling simulation
        run: ./gradlew gatlingEnterpriseUpload -Dgatling.enterprise.simulationId=${{ env.SIMULATION_ID }}

      # Run the simulation on Gatling Enterprise
      - name: Gatling Enterprise Action
        uses: gatling/enterprise-action@v1
        with:
          simulation_id: ${{ env.SIMULATION_ID }}

name: Run Gatling Enterprise Simulation

# Execute the workflow on each push to the main branch
on:
  push:
    branches:
      - main

# Here we use concurrency to cancel previous executions if they are still
# ongoing. Useful to avoid running the same simulation several times
# simultaneously if we push several code changes in a short time.
# See https://docs.github.com/actions/using-jobs/using-concurrency.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# The GATLING_ENTERPRISE_API_TOKEN environment variable is recognized by both
# the Gatling Maven plugin and the gatling/enterprise-action Action
env:
  SIMULATION_ID: '00000000-0000-0000-0000-000000000000'
  GATLING_ENTERPRISE_API_TOKEN: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      # Check out your GitHub repository.
      - name: Checkout
        uses: actions/checkout@v3

      # Set up Java and the build tools (including Maven).
      # You can configure other versions of the JDK, as long as they are
      # supported by your version of Gatling and by your build tool.
      # See https://github.com/actions/setup-java/blob/main/README.md for options.
      - name: Setup JDK
        uses: actions/setup-java@v3
        with:
          distribution: 'zulu'
          java-version: '17'
          cache: 'maven'

      # Build, package, and upload your Gatling project 
      - name: Build Gatling simulation
        run: mvn gatling:enterpriseUpload -Dgatling.enterprise.simulationId=${{ env.SIMULATION_ID }}

      # Run the simulation on Gatling Enterprise
      - name: Gatling Enterprise Action
        uses: gatling/enterprise-action@v1
        with:
          simulation_id: ${{ env.SIMULATION_ID }}

name: Run Gatling Enterprise Simulation

# Execute the workflow on each push to the main branch
on:
  push:
    branches:
      - main

# Here we use concurrency to cancel previous executions if they are still
# ongoing. Useful to avoid running the same simulation several times
# simultaneously if we push several code changes in a short time.
# See https://docs.github.com/actions/using-jobs/using-concurrency.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# The GATLING_ENTERPRISE_API_TOKEN environment variable is recognized by both
# the Gatling Maven plugin and the gatling/enterprise-action Action
env:
  SIMULATION_ID: '00000000-0000-0000-0000-000000000000'
  GATLING_ENTERPRISE_API_TOKEN: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      # Check out your GitHub repository.
      - name: Checkout
        uses: actions/checkout@v3

      # Set up Java.
      # You can configure other versions of the JDK, as long as they are
      # supported by your version of Gatling and by your build tool.
      # See https://github.com/actions/setup-java/blob/main/README.md for options.
      - name: Setup JDK
        uses: actions/setup-java@v3
        with:
          distribution: 'zulu'
          java-version: '17'
          cache: 'maven'

      # Build, package, and upload your Gatling project 
      - name: Build Gatling simulation
        run: ./mvnw gatling:enterpriseUpload -Dgatling.enterprise.simulationId=${{ env.SIMULATION_ID }}

      # Run the simulation on Gatling Enterprise
      - name: Gatling Enterprise Action
        uses: gatling/enterprise-action@v1
        with:
          simulation_id: ${{ env.SIMULATION_ID }}

name: Run Gatling Enterprise Simulation

# Execute the workflow on each push to the main branch
on:
  push:
    branches:
      - main

# Here we use concurrency to cancel previous executions if they are still
# ongoing. Useful to avoid running the same simulation several times
# simultaneously if we push several code changes in a short time.
# See https://docs.github.com/actions/using-jobs/using-concurrency.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# The GATLING_ENTERPRISE_API_TOKEN environment variable is recognized by both
# the Gatling SBT plugin and the gatling/enterprise-action Action
env:
  SIMULATION_ID: '00000000-0000-0000-0000-000000000000'
  GATLING_ENTERPRISE_API_TOKEN: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      # Check out your GitHub repository.
      - name: Checkout
        uses: actions/checkout@v3

      # Set up Java and the build tools (including SBT).
      # You can configure other versions of the JDK, as long as they are
      # supported by your version of Gatling and by your build tool.
      # See https://github.com/actions/setup-java/blob/main/README.md for options.
      - name: Setup JDK
        uses: actions/setup-java@v3
        with:
          distribution: 'zulu'
          java-version: '17'
          cache: 'sbt'

      # Build, package, and upload your Gatling project 
      - name: Build Gatling simulation
        run: sbt Gatling/enterpriseUpload -Dgatling.enterprise.simulationId=${{ env.SIMULATION_ID }}

      # Run the simulation on Gatling Enterprise
      - name: Gatling Enterprise Action
        uses: gatling/enterprise-action@v1
        with:
          simulation_id: ${{ env.SIMULATION_ID }}

Build and update on every push, run weekly

This first workflow is defined in the GitHub repository which contains your Gatling simulation script built with one of our build tools plugins. In this example, every time the code on the main branch gets updated, we build, package, and upload to Gatling Enterprise the current version of the simulation script.

name: Build and update Gatling Enterprise Simulation

# Execute the workflow on each push to the main branch
on:
  push:
    branches:
      - main

# Here we use concurrency to cancel previous executions if they are still
# ongoing. Useful to avoid wasting build time if we push several code changes
# in a short time.
# See https://docs.github.com/actions/using-jobs/using-concurrency.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# The GATLING_ENTERPRISE_API_TOKEN environment variable is recognized by the
# Gatling Gradle plugin
env:
  SIMULATION_ID: '00000000-0000-0000-0000-000000000000'
  GATLING_ENTERPRISE_API_TOKEN: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      # Check out your GitHub repository.
      - name: Checkout
        uses: actions/checkout@v3

      # Set up Java and the build tools (including Gradle).
      # You can configure other versions of the JDK, as long as they are
      # supported by your version of Gatling and by your build tool.
      # See https://github.com/actions/setup-java/blob/main/README.md for options.
      - name: Setup JDK
        uses: actions/setup-java@v3
        with:
          distribution: 'zulu'
          java-version: '17'
          cache: 'gradle'

      # Build, package, and upload your Gatling project 
      - name: Build Gatling simulation
        run: gradle gatlingEnterpriseUpload -Dgatling.enterprise.simulationId=${{ env.SIMULATION_ID }}

name: Build and update Gatling Enterprise Simulation

# Execute the workflow on each push to the main branch
on:
  push:
    branches:
      - main

# Here we use concurrency to cancel previous executions if they are still
# ongoing. Useful to avoid wasting build time if we push several code changes
# in a short time.
# See https://docs.github.com/actions/using-jobs/using-concurrency.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# The GATLING_ENTERPRISE_API_TOKEN environment variable is recognized by the
# Gatling Gradle plugin
env:
  SIMULATION_ID: '00000000-0000-0000-0000-000000000000'
  GATLING_ENTERPRISE_API_TOKEN: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      # Check out your GitHub repository.
      - name: Checkout
        uses: actions/checkout@v3

      # Set up Java.
      # You can configure other versions of the JDK, as long as they are
      # supported by your version of Gatling and by your build tool.
      # See https://github.com/actions/setup-java/blob/main/README.md for options.
      - name: Setup JDK
        uses: actions/setup-java@v3
        with:
          distribution: 'zulu'
          java-version: '17'
          cache: 'gradle'

      # Build, package, and upload your Gatling project 
      - name: Build Gatling simulation
        run: ./gradlew gatlingEnterpriseUpload -Dgatling.enterprise.simulationId=${{ env.SIMULATION_ID }}

name: Build and update Gatling Enterprise Simulation

# Execute the workflow on each push to the main branch
on:
  push:
    branches:
      - main

# Here we use concurrency to cancel previous executions if they are still
# ongoing. Useful to avoid wasting build time if we push several code changes
# in a short time.
# See https://docs.github.com/actions/using-jobs/using-concurrency.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# The GATLING_ENTERPRISE_API_TOKEN environment variable is recognized by the
# Gatling Maven plugin
env:
  SIMULATION_ID: '00000000-0000-0000-0000-000000000000'
  GATLING_ENTERPRISE_API_TOKEN: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      # Check out your GitHub repository.
      - name: Checkout
        uses: actions/checkout@v3

      # Set up Java and the build tools (including Maven).
      # You can configure other versions of the JDK, as long as they are
      # supported by your version of Gatling and by your build tool.
      # See https://github.com/actions/setup-java/blob/main/README.md for options.
      - name: Setup JDK
        uses: actions/setup-java@v3
        with:
          distribution: 'zulu'
          java-version: '17'
          cache: 'maven'

      # Build, package, and upload your Gatling project 
      - name: Build Gatling simulation
        run: mvn gatling:enterpriseUpload -Dgatling.enterprise.simulationId=${{ env.SIMULATION_ID }}

name: Build and update Gatling Enterprise Simulation

# Execute the workflow on each push to the main branch
on:
  push:
    branches:
      - main

# Here we use concurrency to cancel previous executions if they are still
# ongoing. Useful to avoid wasting build time if we push several code changes
# in a short time.
# See https://docs.github.com/actions/using-jobs/using-concurrency.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# The GATLING_ENTERPRISE_API_TOKEN environment variable is recognized by the
# Gatling Maven plugin
env:
  SIMULATION_ID: '00000000-0000-0000-0000-000000000000'
  GATLING_ENTERPRISE_API_TOKEN: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      # Check out your GitHub repository.
      - name: Checkout
        uses: actions/checkout@v3

      # Set up Java.
      # You can configure other versions of the JDK, as long as they are
      # supported by your version of Gatling and by your build tool.
      # See https://github.com/actions/setup-java/blob/main/README.md for options.
      - name: Setup JDK
        uses: actions/setup-java@v3
        with:
          distribution: 'zulu'
          java-version: '17'
          cache: 'maven'

      # Build, package, and upload your Gatling project 
      - name: Build Gatling simulation
        run: ./mvnw gatling:enterpriseUpload -Dgatling.enterprise.simulationId=${{ env.SIMULATION_ID }}

name: Build and update Gatling Enterprise Simulation

# Execute the workflow on each push to the main branch
on:
  push:
    branches:
      - main

# Here we use concurrency to cancel previous executions if they are still
# ongoing. Useful to avoid wasting build time if we push several code changes
# in a short time.
# See https://docs.github.com/actions/using-jobs/using-concurrency.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# The GATLING_ENTERPRISE_API_TOKEN environment variable is recognized by the
# Gatling SBT plugin
env:
  SIMULATION_ID: '00000000-0000-0000-0000-000000000000'
  GATLING_ENTERPRISE_API_TOKEN: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      # Check out your GitHub repository.
      - name: Checkout
        uses: actions/checkout@v3

      # Set up Java and the build tools (including SBT).
      # You can configure other versions of the JDK, as long as they are
      # supported by your version of Gatling and by your build tool.
      # See https://github.com/actions/setup-java/blob/main/README.md for options.
      - name: Setup JDK
        uses: actions/setup-java@v3
        with:
          distribution: 'zulu'
          java-version: '17'
          cache: 'sbt'

      # Build, package, and upload your Gatling project 
      - name: Build Gatling simulation
        run: sbt Gatling/enterpriseUpload -Dgatling.enterprise.simulationId=${{ env.SIMULATION_ID }}

This second workflow may be defined in the same repository or another one. Once a week (based on a CRON expression), we run the simulation on Gatling Enterprise.

name: Run Gatling Enterprise Simulation

# Execute the workflow every Sunday at 2 AM UTC, using POSIX CRON syntax. See:
# https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
on:
  schedule:
    - '0 2 * * 0'

jobs:
  run:
      # Run the simulation on Gatling Enterprise
      - name: Gatling Enterprise Action
        uses: gatling/enterprise-action@v1
        with:
          api_token: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}
          simulation_id: '00000000-0000-0000-0000-000000000000'

Edit this page on GitHub

GitHub Actions

Purpose of this GitHub Action#

Action coordinates#

Pre-requisites#

Quickstart (minimal job configuration)#

Configuration reference#

Inputs#

Outputs#

Logs#

Cancellation#

Sample use cases#

Build and run simulation#

Build and update on every push, run weekly#