Running Suites from CI/CD

A saved PruTAN suite can be triggered directly from your CI/CD pipeline, so a suite run becomes a step in your build or release process — the build passes only when every script (and validation assertion) in the suite passes.

PruTAN generates ready-to-use snippets for Jenkins, GitHub Actions, AWS CodeBuild, and cURL. Each snippet is pre-filled with the current suite's details, and each authenticates with a PruTAN API key that you keep in your CI tool's secret store — never in the pipeline file itself.

Prerequisites

• A saved suite. CI/CD triggers run a stored suite, so build and save the suite first (see Suites).
• An API key for the suite's team. Create one under Settings → API Keys (see API Keys). Treat it like a password.

Opening the CI/CD configuration

Open the saved suite so its Run Configuration panel appears on the right. At the bottom of that panel, select Copy configuration for: CI/CD.

The Run from CI/CD dialog

The Run from CI/CD dialog opens with one tab per platform. Pick the tab for your pipeline, choose the Environment the run should target (top-right), and copy the snippet with the copy icon. Each snippet is syntax-highlighted for its language, and the filename it belongs in (for example Jenkinsfile) is shown above the code.

How the snippets work

The Jenkins, GitHub, and AWS snippets embed a small Python runner that:

1. Triggers the suite via POST /router/execute/suite/plan.
2. Polls /multi/suite/history until the run finishes.
3. Prints an execution report and fails the build if any test — or validation assertion — fails.

They read their settings (base URL, suite name/GUID, environment GUID, and shared content) from parameters/variables you control, and read the API key from a secret. The cURL command instead embeds the suite's identity directly and triggers the run without polling.

Jenkins

The Jenkins tab produces a declarative Jenkinsfile. It reads the API key from a Jenkins credential (credentials('API_KEY')) and takes everything else as build parameters.

1. Store the API key as a credential. In your Jenkins instance go to Manage Jenkins → Credentials → System → Global credentials → Add Credentials. Choose Secret text, paste your PruTAN API key, and set the ID to exactly API_KEY.

2. Create a Pipeline job. New Item → Pipeline, then paste the copied Jenkinsfile into the Pipeline script box and save.
3. Review the parameters. PRUTAN_URL, SUITE_NAME, SUITE_GUID, and ENVIRONMENT_GUID are pre-filled from the suite, and DATA_STITCHING defaults to this suite's Shared Content setting. PYTHON is optional and only used on Windows agents — leave it empty on Linux (the pipeline uses python3 and builds its own virtual environment), and set it to the full path of python.exe only when the agent is Windows.
4. Run. Choose Build with Parameters. The Validate stage confirms the credential resolved (API_KEY : (set)), then the console triggers the suite, polls it, and ends with the PruTAN execution report — Build Status : SUCCESS when everything passes, or a red build if any test or validation assertion fails.

How the secret is used in the script

The key never appears in the pipeline text. Jenkins injects it at runtime through the environment block, which binds the credential (ID API_KEY) to an environment variable of the same name:

environment {
    API_KEY = credentials('API_KEY')   // pulls the "Secret text" credential
}

The Run Prutan Suite stage forwards that variable to the Python runner, which sends it as the PruTAN auth header:

withEnv(["API_KEY=${API_KEY}", /* PRUTAN_URL, SUITE_GUID, … */]) {
    sh '.prutan_venv/bin/python prutan_runner.py'
}

API_KEY = env("API_KEY")
HEADERS = {"API-KEY": API_KEY, "Content-Type": "application/json"}

Jenkins masks the value in the console log (it shows as ****), and the Validate stage prints only whether it resolved (API_KEY : (set)).

GitHub Actions

The GitHub tab produces a workflow_dispatch (manually triggered) workflow. It reads the API key from a repository secret and takes the rest as workflow inputs. GitHub's runners install Python automatically (via actions/setup-python), so nothing extra is needed on the runner.

1. Store the API key as a secret. In your repository (for example, your-org/your-repo) go to Settings → Secrets and variables → Actions → New repository secret. Name it API_KEY and paste your PruTAN API key.

2. Add the workflow. Commit the copied YAML to a workflow file under .github/workflows/ (for example prutan-suite-test.yml) on your default branch.
3. Run it. Open the Actions tab, select Prutan-Suite-Common-Execution-Test, click Run workflow, and confirm or adjust the pre-filled inputs (base URL, suite GUID, environment GUID, data stitching). The key is injected from secrets.API_KEY — it is never entered as a workflow input.

How the secret is used in the script

The workflow reads the secret only inside the run step's env: map, which maps secrets.API_KEY to an environment variable the runner reads — the secret is never a workflow input, so it stays out of the run's input history:

- name: Run Prutan Suite
  env:
    API_KEY: ${{ secrets.API_KEY }}
    PRUTAN_URL: ${{ github.event.inputs.PRUTAN_URL }}
    # SUITE_GUID, ENVIRONMENT_GUID, DATA_STITCHING …
  run: python prutan_runner.py

API_KEY = env("API_KEY")
HEADERS = {"API-KEY": API_KEY, "Content-Type": "application/json"}

GitHub automatically masks the secret in the logs.

The job installs Python, triggers the suite, polls until it finishes, and prints the PruTAN execution report, exiting non-zero if any test or validation (pvOutput) assertion fails. The run below passed — the report ends with Build Status : SUCCESS and All Prutan tests passed! Ready to deploy.

AWS CodeBuild

The AWS tab produces a buildspec.yml. It reads the API key from AWS Secrets Manager and takes the rest as build environment variables.

1. Store the API key in Secrets Manager. Create a secret (for example prutan/api-key) holding your PruTAN API key.
2. Add the buildspec. Commit the copied buildspec.yml to your source repository. Its env → secrets-manager block maps the secret into API_KEY; adjust the secret id / JSON key to match yours.
3. Set the suite variables. PRUTAN_URL, SUITE_NAME/SUITE_GUID, ENVIRONMENT_GUID, and DATA_STITCHING are baked into the buildspec, or you can override them under the CodeBuild project's Environment variables.
4. Run the build and review the logs for the execution report.

How the secret is used in the script

CodeBuild resolves the secret at the start of the build through the env → secrets-manager block, which maps a Secrets Manager entry to the API_KEY environment variable. Unlike the plain variables block, values pulled here are treated as secrets and masked in the log:

env:
  variables:
    PRUTAN_URL: "https://app.prutan.com/prutan/core"
    # SUITE_GUID, ENVIRONMENT_GUID, DATA_STITCHING …
  secrets-manager:
    API_KEY: "prutan/api-key"        # <secret-id>[:<json-key>]

The runner — written to prutan_runner.py during the build phase — reads that variable and sends it as the auth header:

API_KEY = env("API_KEY")
HEADERS = {"API-KEY": API_KEY, "Content-Type": "application/json"}

The plaintext key never appears in the buildspec.yml or the build log.

cURL

The cURL tab is a direct call to /router/execute/suite/plan, pre-filled with the suite's name, environment, and shared-content flag. Use the macOS / Linux (multi-line) or Windows (single-line) toggle to match your shell, then replace <YOUR_API_KEY> with your key.

Unlike the pipeline snippets, cURL only triggers the run — it does not poll for the result or fail on test failures. It is handy for a quick manual kick-off or a lightweight custom script.