Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 36 ยท CI and Cloud

Running k6 in CI/CD Pipelines

Run k6 smoke and load tests in CI: exit codes and thresholds as gates, GitHub Actions and GitLab CI examples, what to run on pull requests versus nightly, and how to keep results trustworthy.

A load test you run by hand once a quarter finds problems after they ship. A test that runs in your pipeline finds the commit that made the checkout 40 % slower while the author still remembers writing it. k6 is built for this: it is a single binary, it takes a script and returns an exit code, and thresholds turn performance goals into pass/fail.

Honesty note. k6 and CI runners do not run on this site, so YAML and shell commands are read-only. The runnable blocks are Node stand-ins that reproduce the decision logic (thresholds to exit code), which is the heart of a performance gate.

The contract between k6 and a pipeline

CI systems only understand one thing: a process exits with 0 (success) or non-zero (failure). k6 maps test results to exit codes:

Exit code Meaning
0 Test finished; all thresholds passed
99 One or more thresholds failed
107 A script exception (for example an uncaught error in init)
108 The test was aborted by the script (exec.test.abort())
109 The test was stopped externally (for example Ctrl+C)

You rarely need the exact number; you need the non-zero exit. But distinguishing 99 ("the system is too slow") from 107 ("the script is broken") helps triage.

So the gate is simply your thresholds:

JavaScript
export const options = {
  vus: 10,
  duration: '1m',
  thresholds: {
    http_req_failed: ['rate<0.01'],
    http_req_duration: ['p(95)<500'],
    checks: ['rate>0.99'],
  },
};

If a threshold crosses, k6 prints the failing line, exits with 99, and the pipeline step turns red. To stop a runaway test early rather than wait for the end, use the object form with abortOnFail:

JavaScript
thresholds: {
  http_req_failed: [{ threshold: 'rate<0.05', abortOnFail: true, delayAbortEval: '10s' }],
}

delayAbortEval gives the system time to warm up before a threshold can abort the run.

Node.js Stand-in: thresholds decide the exit code

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

What to run where

Not every pipeline stage should run the same test. A sensible layering:

Stage Test Duration Purpose
Pull request Smoke: 1-5 VUs, a few iterations 30-60 s Script and endpoints still work; no obvious regression
After merge / on staging Load: realistic traffic 5-15 min Compare against SLO thresholds
Nightly or weekly Stress / soak 30 min - hours Capacity, leaks, degradation
Before big launches Spike / breakpoint (manual) Varies Find the limits

Smoke tests on every pull request are cheap and catch broken endpoints. Heavy tests on every commit waste money and, because shared environments are noisy, cause flaky failures that teach developers to ignore the gate.

GitHub Actions example

Grafana publishes official actions that install and run k6. A minimal workflow (read-only):

YAML
name: performance
on:
  pull_request:
  schedule:
    - cron: '0 2 * * *'     # nightly at 02:00 UTC

jobs:
  smoke:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: grafana/setup-k6-action@v1
      - uses: grafana/run-k6-action@v1
        with:
          path: tests/smoke.js
        env:
          BASE_URL: ${{ vars.STAGING_URL }}
          API_TOKEN: ${{ secrets.LOADTEST_TOKEN }}

  load:
    if: github.event_name == 'schedule'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: grafana/setup-k6-action@v1
      - run: k6 run --summary-export=summary.json tests/load.js
        env:
          BASE_URL: ${{ vars.STAGING_URL }}
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: k6-summary
          path: summary.json

Note if: always() on the upload: you want the report precisely when the test fails. Secrets go through env, and the script reads them with __ENV.

A GitLab CI job has the same shape using the official image:

YAML
k6-smoke:
  image:
    name: grafana/k6:latest
    entrypoint: ['']
  script:
    - k6 run tests/smoke.js
  artifacts:
    when: always
    paths: [summary.json]

Pin the image or action to a version in real pipelines so a new k6 release cannot change your gate overnight.

Making CI results trustworthy

  • Same environment every time. A shared staging server being deployed to during your test produces random failures. Reserve a window or use a dedicated environment.
  • Generate load from a decent machine. A tiny CI runner can be the bottleneck; watch for dropped_iterations and high CPU on the runner.
  • Keep thresholds realistic. Start from a measured baseline plus a margin (for example baseline p(95) times 1.3). Tighten later.
  • Test the test. Run it against a known-good build first, and a deliberately slow one to prove the gate can fail.
  • Publish the numbers. Upload summary.json or the HTML report as an artifact and trend them over time.
flowchart LR
    A["Commit / PR"] --> B["Build and deploy to staging"]
    B --> C["k6 smoke test"]
    C -->|thresholds pass| D["Merge allowed"]
    C -->|exit code 99| E["Block and attach report"]
    F["Nightly schedule"] --> G["k6 load test"] --> H["Trend dashboard"]

Smoke tests gate pull requests; heavier scheduled tests feed a trend dashboard.

Node.js Stand-in: compare against a baseline with a margin

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What exit code does k6 return when a threshold fails?

    k6 exits with 99 when thresholds fail, and 0 when everything passes.
  2. 2. Which test belongs on every pull request?

    Smoke tests are quick and cheap: they confirm the script and endpoints work without loading shared environments heavily.
  3. 3. Why use 'if: always()' on the artifact upload step?

    A failed k6 step stops later steps by default. always() ensures you still get the report that explains the failure.
  4. 4. What does abortOnFail with delayAbortEval do?

    abortOnFail ends the test as soon as the threshold is crossed; delayAbortEval postpones that evaluation to avoid warm-up noise.

Summary

  • Thresholds turn goals into exit codes: 0 pass, 99 threshold failure.
  • Layer tests: smoke on PRs, load after merge, soak and stress on schedules.
  • Use the official actions or image, pin versions, pass secrets via env.
  • Always upload the summary, keep environments stable and thresholds realistic.

Next: k6 in Docker and Kubernetes