Documentation › CI/CD Integration

CI/CD Integration

User Trigger MaxTAF runs from your pipeline and fail the build when tests fail.

Because everything in MaxTAF is available over the REST API, wiring it into a pipeline is straightforward: store an API key as a secret, POST to run a case or suite, and check the result. This page gives you a reusable recipe and ready-made snippets.

The pattern

Store credentials as encrypted CI secrets: MAXTAF_API_KEY and MAXTAF_PROJECT_ID (and MAXTAF_URL if on-prem).
Trigger a run — POST to the run-by-name endpoint. Run synchronously (SYNC) so the call returns only when the run has finished.
Evaluate the result — inspect the run result and exit non-zero on failure so the pipeline stage fails.
(Optional) publish artefacts — pull the run report / Allure results for your build summary.

Run a suite, not a case

For a regression gate, point CI at a suite — you get one call, parallel execution and a consolidated Allure report. Use /api/maxtaf/suites/name/api/runs?suiteName=….

A portable shell script

This works in any runner that has curl. It triggers a synchronous suite run and fails if the result isn't a success.

#!/usr/bin/env bash
set -euo pipefail

: "${MAXTAF_URL:=https://mx1.maxtaf.com}"
: "${MAXTAF_API_KEY:?set MAXTAF_API_KEY}"
: "${MAXTAF_PROJECT_ID:?set MAXTAF_PROJECT_ID}"
SUITE_NAME="${1:-Regression}"

echo "Running MaxTAF suite: ${SUITE_NAME}"
resp=$(curl -sS -X POST \
  "${MAXTAF_URL}/api/maxtaf/suites/name/api/runs?suiteName=${SUITE_NAME}" \
  -H "X-Maxtaf-Api-Key: ${MAXTAF_API_KEY}" \
  -H "X-Project-Id: ${MAXTAF_PROJECT_ID}" \
  -H "X-User-TimeZone-Id: UTC" \
  -H "Accept: application/json" \
  -F 'runDetails={"repeatRun":"1","syncAsync":"SYNC","parallelSerial":"PARALLEL","runParams":"","runParamsType":"PRIORITY","parentRunId":null};type=application/json')

echo "Response: ${resp}"

# Fail the build unless the run result is a success.
if echo "${resp}" | grep -Eiq '"(result|state)"\s*:\s*"(SUCCESS|PASSED)"'; then
  echo "✅ MaxTAF suite passed"
else
  echo "❌ MaxTAF suite did not pass"
  exit 1
fi

Match the result check to your response

The exact result/state labels are listed under run states. Confirm the field names by running the call once and inspecting the JSON, then tighten the grep (or parse with jq) to your environment.

GitHub Actions

name: maxtaf-regression
on:
  workflow_dispatch:
  schedule: [{ cron: "0 2 * * *" }]   # nightly
jobs:
  regression:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run MaxTAF suite
        env:
          MAXTAF_URL: https://mx1.maxtaf.com
          MAXTAF_API_KEY: ${{ secrets.MAXTAF_API_KEY }}
          MAXTAF_PROJECT_ID: ${{ secrets.MAXTAF_PROJECT_ID }}
        run: ./ci/run-maxtaf.sh Regression

Jenkins (declarative pipeline)

pipeline {
  agent any
  environment {
    MAXTAF_URL        = 'https://mx1.maxtaf.com'
    MAXTAF_API_KEY    = credentials('maxtaf-api-key')
    MAXTAF_PROJECT_ID = 'acme_maximo_regression'
  }
  stages {
    stage('MaxTAF Regression') {
      steps {
        sh './ci/run-maxtaf.sh Regression'
      }
    }
  }
}

GitLab CI

maxtaf-regression:
  image: curlimages/curl:latest
  variables:
    MAXTAF_URL: "https://mx1.maxtaf.com"
  script:
    - MAXTAF_API_KEY="$MAXTAF_API_KEY" MAXTAF_PROJECT_ID="$MAXTAF_PROJECT_ID" ./ci/run-maxtaf.sh Regression
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'

Async + poll (for long suites)

If a run is long, trigger it with "syncAsync":"ASYNC", capture the returned run id, then poll GET /api/maxtaf/runs/{id} until the state is terminal and check the result. This avoids holding an HTTP connection open for the whole run.

Passing parameters per run

Use the runParams field of runDetails to override parameters for a single run — for example to target a specific environment URL without editing cases. Combine with runParamsType to control precedence. See the Parameter reference.

REST API Reference · API-key hygiene · Run states