Official GitHub Action for running Locust tests

[ta4ilka69]

Prerequisites

• I am using the latest version of Locust
• I am suggesting a new feature, not asking a question

Description

Hi!
I propose the creation of an official or community-supported GitHub Action to simplify running Locust tests within CI/CD pipelines. This would abstract away the manual steps of setting up Python, installing dependencies, and running the locust command.
A great example of it is Grafana k6's GitHub Action (https://github.com/grafana/run-k6-action).
I suggest similar action for Locust, let's call it run-locust-action. A user's workflow could look like this:

on:
  push:

jobs:
  locust-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Locust test
        uses: locustio/run-locust-action@v1
        with:
          # Required inputs
          locust-file: 'tests/my_locust_file.py'
          host: 'https://my-staging-app.com'

          # Optional inputs for load configuration
          users: 50
          spawn-rate: 10
          run-time: '2m'

          # Optional inputs for pass/fail criteria
          check-fail-ratio: 0.02 # Fail if error rate > 2%
          check-avg-response-time: 500 # Fail if avg response time > 500ms

          # Optional: Automatically upload HTML/CSV reports as artifacts
          upload-artifacts: true

I'd love to hear your thoughts on this proposal. I'm also willing to help with the implementation if the team finds this idea valuable.

[cyberw]

Love it!

If you want to create a first implementation I would be happy to add a repo under locustio and have it be part of our official stuff.

Regarding upload-artifacts, perhaps we can just assume that --html, --csv and --json-file means we want to upload them.

[ta4ilka69]

I'm glad to hear that, and I'll start implementing it.

[Hchanni]

Hey @ta4ilka69 any update on this? I'm looking to do something like this internally at my company, and I wouldn't contributing to something open source to help others if you don't have the bandwidth to see this through :)

[ta4ilka69]

Hey @Hchanni,

I’m currently writing tests and expect to publish an MVP within the next two weeks. I plan to hand the project over to the locustio org. If your team builds an alternative or has improvements, fill free to collaborate so the maintainers can choose or combine approaches.

[ta4ilka69]

@cyberw I’ve built a GitHub Action to run Locust in CI (thresholds, HTML/CSV artifacts, tags, version pinning, pip cache). CI is green (incl. expected-fail jobs). Repo — feedback welcome!

[cyberw]

Real interesting! Couple of things:

• Are you sure we want to use explicitly named parameters instead of just passing anything to locust? For the action to be as robust as possible when Locust changes, we should list as few as possible parameters as necessary (and, if possible, pick up the same env vars and .conf file arguments)
• For things like check_fail_ratio, maybe we can use jq instead? I'd like it to be useable without the Action (and not have to maintain both). In locust-plugins we do the check inside the Locust run, which is another option. https://github.com/SvenskaSpel/locust-plugins/blob/master/locust_plugins/__init__.py#L208

Haven't tested it hands on yet, but will have a go next week and/or as soon as you address my comments :)

[cyberw]

Also, instead of having settings for things like python-version etc, isn't it more robust if we ask users to use a standard python setup action (astral-sh/setup-uv@v2 or actions/setup-python@v6) first? I'm not a GH actions developer, but it kinda feels like a more flexible and less-work-for-us approach :)

[ta4ilka69]

I will figure it out on this week, thx for feedback!

[ta4ilka69]

Coming back with updates after the fixes. I’ve tried to follow your feedback - if I missed or misunderstood anything, please let me know. The changes are available in this branch.
I also added a small Flask-based REST sample and included its load test in CI. CI now verifies both:

• running Locust via the new action, and
• running via a plain shell script without the action (to validate dependency installation/caching)

If this job feels unnecessary for the final version, I can remove or revert it before pr to main or with your next comments.

[cyberw]

Cool stuff. Can you open a PR? Easier to reveiew diff, comment on it etc

[ta4ilka69]

ta4ilka69/locust-github-action#1