Run tests in CI/CD with the ktm CLI

ktm is built for pipelines. The pattern is always the same: build a campaign, run it, publish the results. The CLI returns JSON, writes JUnit XML, and exits non-zero when tests fail, so your pipeline reacts automatically.

Pipeline examples

name: Kapptivate Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install ktm
        run: curl -fsSL https://artefacts.kapptivate.com/ktm/install.sh | bash

      - name: Build campaign
        env:
          KAPPTIVATE_API_KEY: ${{ secrets.KAPPTIVATE_API_KEY }}
        run: |
          ktm ci build \
            --test-ids 16480,16838 \
            --product acme~web --variant "API:Staging" > campaign.json

      - name: Run tests
        env:
          KAPPTIVATE_API_KEY: ${{ secrets.KAPPTIVATE_API_KEY }}
        run: |
          ktm ci run \
            --test-config-path campaign.json \
            --junit-file results.xml \
            --output-file summary.json

      - name: Upload results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: |
            results.xml
            summary.json

For GitLab, add KAPPTIVATE_API_KEY as a masked CI/CD variable in your project settings (Settings > CI/CD > Variables), the same way GitHub Actions uses secrets.KAPPTIVATE_API_KEY.

Native GitHub integration

When GITHUB_ACTIONS=true (set automatically), ktm produces native output with no extra configuration:

• It emits ::notice and ::error annotations that appear on the run and on pull requests.
• It appends a results table to the job summary.

The JSON summary is suppressed on stdout in that mode, so pass --output-file summary.json to keep it as a file.

Other platforms

For Jenkins and other runners, the pattern is the same: install ktm, set KAPPTIVATE_API_KEY, then call ktm ci build and ktm ci run. Commit your campaign JSON or test configs to the repo and point ktm ci run --test-config-dir ./tests/ at them.

Exit codes

The pipeline fails on any non-zero exit. Code 5 means tests ran but some failed (distinct from 1, a general error). See Configuration for the full list.

What's next?