Add k6 as a CI/CD pipeline step

Every major CI/CD platform can run k6. For GitHub Actions, Grafana provides two official actions: grafana/setup-k6-action installs k6, and grafana/run-k6-action executes your scripts. For GitLab CI and other platforms, the portable approach is the grafana/k6 Docker image.

This milestone uses GitHub Actions as the primary example and includes a GitLab CI variant. The concepts are the same on every platform: run k6, pass environment variables, and let the exit code determine the job result.

To add k6 as a pipeline step, complete the following steps:

1. Commit your parameterized k6 test script to your repository. Place it in a dedicated folder for test scripts:

   Bash Copy

   mkdir -p tests/performance
   cp test.js tests/performance/test.js
   git add tests/performance/test.js
   git commit -m "Add k6 performance test script"

2. Create a GitHub Actions workflow file at .github/workflows/performance.yml:

   YAML Copy

   name: Performance Test
   
   on:
     push:
       branches: [main]
     pull_request:
       branches: [main]
   
   jobs:
     k6-test:
       runs-on: ubuntu-latest
       steps:
         - name: Checkout
           uses: actions/checkout@v4
   
         - name: Setup k6
           uses: grafana/setup-k6-action@v1
   
         - name: Run k6 test
           uses: grafana/run-k6-action@v1
           with:
             path: tests/performance/test.js
             flags: --env BASE_URL=https://staging.example.com

   Replace https://staging.example.com with the URL of the environment you want to test. You can also pass BASE_URL with a step-level env: block instead of --env in flags.

3. If you use GitLab CI, add the following job to your .gitlab-ci.yml instead:

   YAML Copy

   performance-test:
     image:
       name: grafana/k6:latest
       entrypoint: ['']
     stage: test
     script:
       - k6 run -e BASE_URL=https://staging.example.com tests/performance/test.js

Tip: If your CI platform doesn’t have a dedicated k6 action, use the Docker image directly:

Bash Copy

docker run --rm -e BASE_URL=https://staging.example.com \
  -v "$(pwd)/tests:/tests" grafana/k6:latest run /tests/performance/test.js

1. Push your pipeline configuration to trigger a build:

   Bash Copy

   git add .github/workflows/performance.yml
   git commit -m "Add k6 performance test to pipeline"
   git push

   Your CI platform runs the k6 test as part of the pipeline. The test output appears in the pipeline logs.

In the next milestone, you configure your pipeline to act on the k6 exit code so that threshold breaches block deployments.