perfscale GitLab CI templates

Run a load test with perfscale — k6, locust, or perfscale's own native step engine — from a GitLab CI pipeline, and collect the metrics as a job artifact.

What it does

The .perfscale:run template downloads the pinned perfscale release binary (linux/amd64 or linux/arm64), verifies its sha256 against the release's sha256sums.txt, runs your test, and keeps the machine-readable perfscale-summary.json (requests, RPS, latency percentiles, error rate + engine/VUs/duration/timestamp metadata) as a job artifact. A second template, .perfscale:gate, fails the pipeline when a metric from that summary exceeds its budget.

Usage

Include the templates and extend the hidden jobs:

include:
  - remote: https://raw.githubusercontent.com/Perfscale/gitlab-ci/main/templates/perfscale.gitlab-ci.yml
  - remote: https://raw.githubusercontent.com/Perfscale/gitlab-ci/main/templates/gate.gitlab-ci.yml

load-test:
  extends: .perfscale:run
  variables:
    PERFSCALE_K6: tests/load/script.js

Set exactly one of PERFSCALE_K6, PERFSCALE_LOCUST, or PERFSCALE_FILE:

# k6
load-test:
  extends: .perfscale:run
  variables:
    PERFSCALE_K6: script.js

# locust
load-test:
  extends: .perfscale:run
  variables:
    PERFSCALE_LOCUST: locustfile.py
    PERFSCALE_HOST: https://example.com

# native step engine (requires config)
load-test:
  extends: .perfscale:run
  variables:
    PERFSCALE_FILE: test.yaml
    PERFSCALE_CONFIG: config.yaml

Full pipeline example

include:
  - remote: https://raw.githubusercontent.com/Perfscale/gitlab-ci/main/templates/perfscale.gitlab-ci.yml
  - remote: https://raw.githubusercontent.com/Perfscale/gitlab-ci/main/templates/gate.gitlab-ci.yml

stages:
  - loadtest
  - gate

load-test:
  stage: loadtest
  extends: .perfscale:run
  variables:
    PERFSCALE_FILE: examples/hello.test.yaml
    PERFSCALE_CONFIG: examples/hello.config.yaml

p95-gate:
  stage: gate
  extends: .perfscale:gate
  needs: [load-test]   # downloads the run job's summary artifact
  variables:
    PERFSCALE_GATE_METRIC: ".summary.p95_ms"
    PERFSCALE_GATE_MAX: "500"

The gate reads the summary artifact produced by the run job, so it must run after it — via needs: (recommended) or simply in a later stage. See examples/.gitlab-ci.yml for runnable k6 and native-engine pipelines.

Variables

.perfscale:run

Variable	Default	Description
PERFSCALE_VERSION	latest	perfscale release to install (tag like v0.2.0, or latest). Pin a tag for air-gapped setups.
PERFSCALE_K6	—	Path to a k6 .js script (perfscale run --k6).
PERFSCALE_LOCUST	—	Path to a locustfile (perfscale run --locust).
PERFSCALE_FILE	—	Path to a native test.yaml (perfscale run -f). Requires PERFSCALE_CONFIG.
PERFSCALE_CONFIG	—	Path to config.yaml (-c). Required with PERFSCALE_FILE, optional for locust.
PERFSCALE_HOST	—	Target base URL for the locust engine (--host).
PERFSCALE_ARGS	—	Extra raw arguments appended verbatim to perfscale run.
PERFSCALE_REPORT	—	POST the summary to a perfscale serve instance (--report).
PERFSCALE_SUMMARY	perfscale-summary.json	Path of the machine-readable JSON summary (--summary-export); kept as an artifact.
PERFSCALE_ARCH	amd64	Binary architecture: amd64 or arm64.
PERFSCALE_DOWNLOAD_BASE	https://github.com/Perfscale/perfscale/releases	Base URL of the release tree. Override to fetch the binary from your own artifact host.

.perfscale:gate

Variable	Default	Description
PERFSCALE_SUMMARY	perfscale-summary.json	Summary file to read (must match the run job).
PERFSCALE_GATE_METRIC	.summary.p95_ms	jq path of the metric to check; must resolve to a number.
PERFSCALE_GATE_MAX	500	Budget: the job fails when the metric is greater than this value.

Exit codes

The job mirrors the CLI: 0 = the run completed (even if requests/checks failed), 1 = the run could not execute (missing file, invalid YAML, engine binary not found, engine crashed before producing results), 2 = invalid arguments — also used by the template's own variable validation (e.g. zero or two engines selected).

A green job does not mean your SLA held. perfscale exits 0 whenever the run executed, even with failed requests or a blown latency budget. Put a .perfscale:gate job after the run to fail the pipeline on a metric from the exported summary.

Self-managed / enterprise GitLab

The templates work on any GitLab instance with a docker executor on linux runners, but two things point at github.com by default.

Including the template. include: remote makes the GitLab instance fetch the file from raw.githubusercontent.com. If your instance cannot reach github.com, either download templates/*.gitlab-ci.yml into your own repository and use include: local:

include:
  - local: '/ci/perfscale.gitlab-ci.yml'
  - local: '/ci/gate.gitlab-ci.yml'

or mirror Perfscale/gitlab-ci into your instance and use include: project:

include:
  - project: 'your-group/gitlab-ci'
    ref: main
    file: '/templates/perfscale.gitlab-ci.yml'
  - project: 'your-group/gitlab-ci'
    ref: main
    file: '/templates/gate.gitlab-ci.yml'

Downloading the binary. The job fetches the perfscale binary and sha256sums.txt from github.com/Perfscale/perfscale/releases. In an air-gapped network, mirror the release assets to an artifact host your runners can reach, keeping the release layout:

<host>/perfscale/releases/download/<tag>/perfscale-linux-amd64
<host>/perfscale/releases/download/<tag>/perfscale-linux-arm64
<host>/perfscale/releases/download/<tag>/sha256sums.txt

then point the job at it and pin a version (the /latest redirect only exists on github.com):

load-test:
  extends: .perfscale:run
  variables:
    PERFSCALE_K6: script.js
    PERFSCALE_DOWNLOAD_BASE: "https://artifacts.example.com/perfscale/releases"
    PERFSCALE_VERSION: "v0.2.0"

License

MIT