Integrations

Running CAT from a pipeline or a scheduler is one command. This page lists what that command needs around it — plan, license key, tool, secrets, results, exit codes — and points to the platform guides.

Plan it first #

Before the first pipeline step, settle three questions — and draw the answer; it is the picture that makes the allow-list request, the upgrade procedure and the “why can’t it see the warehouse” conversation short.

Draw it as above with your names in the boxes — the agent pool, the warehouse, the workspace — and the rest of this page fills in the facts.

Plan #

Automated use — a run started by a CI/CD platform or a scheduler — is an Enterprise plan feature. The Starter, Professional and Team plans are interactive-only: a run they would otherwise allow is refused when CAT sees it was launched by automation, with The 'Team' plan allows interactive use only; CAT was launched by 'GitHub Actions'. Run CAT interactively, or upgrade your plan. (CAT CLI exit code 6; PowerShell error CatPortal.InteractiveUsageRequired; Python InteractiveUsageError). See Compare plans.

Enforced from CAT 3.0: a run started by a CI/CD platform or a scheduler without a valid Enterprise license key stops before any test runs. Earlier versions let such runs through; when a pipeline moves to 3.0, add the license-key step before bumping the version — which is one more reason to pin the version and keep it in a variable.

CAT recognizes automation two ways, and refuses only on a confident match — nothing detected means the run is allowed:

Sign-in: the license key #

A pipeline has no browser and nobody to type a password. On the Enterprise plan CAT signs in with nothing: the license key unlocks every tool, also without Internet access.

The simplest way is the CAT_LICENSE_KEY environment variable: map the secret that holds the key to a variable of that name on the step, and every CAT tool reads it — no set-key command, nothing stored on the agent. While the variable is set it is the key in effect, and a value CAT cannot use stops the run instead of falling back to anything else (CAT CLI exits 8).

A self-hosted agent can instead keep the key stored under the account the agent runs as, set once with the commands below; then don’t map the variable at all:

Moved from Enterprise to Team? Remove the CAT_LICENSE_KEY mapping from the pipeline. The expired key in the variable now refuses the run rather than falling through to the CAT_PORTAL_TOKEN sign-in.

The key is shared by all CAT tools on the machine. See Get CAT license and Apply a license key.

Tool #

One command runs the project: catcli run, Invoke-CatProject, invoke_project(). The project file, the test definitions and everything they reference are read from the checkout; relative paths resolve against the project file.

Pre-installed on the agent, or installed by the pipeline #

The platform guides install CAT in a pipeline step, because that works on any agent — hosted ones included. The other normal setup, on self-hosted agents, is to treat CAT as a component of the machine: install it once (pinned), set the license key once under the account the agent runs as, and manage updates with the same process as the rest of the server’s software. The pipeline step is then just the run command, and the agent needs no access to the package sources at all.

For networks that allow-list outbound addresses, this is what each route reaches:

Pin the version, keep version and key in variables #

A pipeline that installs “the latest CAT” changes behaviour the day a new version ships — with 3.0, a pipeline that has no license-key step stops working the day it picks the new version up. Pin the version, and keep the two values every CAT step needs — the version and the license key — in pipeline variables (a variable group, CI/CD variables, repository secrets, Jenkins credentials), not in the script: upgrading CAT is then one variable change in one place, and the key is a secret the platform masks.

followed by the key from the table above (Set-CatInstance -LicenseKey $env:CAT_LICENSE_KEY, …). The platform guides below use CAT_VERSION and CAT_LICENSE_KEY this way.

Secrets #

Connection strings, passwords and tokens never go into the project file. Write %NAME% where the value belongs — Connection string: "%DWH_CONNECTION_STRING%" — and CAT reads the environment variable NAME when it opens the project. Every platform can inject a secret as an environment variable of the step, so the project file runs unchanged on a laptop and in the pipeline. See Environment variables and Work with passwords.

Results and exit codes #

Platforms render test results from a report file: ask for one with the Output setting — JUnit is read by Azure DevOps, GitLab, GitHub Actions and Jenkins; TRX by Azure DevOps and Visual Studio. Files are written after the run; a database output writes each test as it finishes.

CAT CLI fails the step on a failed test (exit code 10; --exitCode run to keep 0); the PowerShell module and the Python module do not, the publish step or a summary check does. catcli run exits 10 unless every selected test passed; Invoke-CatProject throws nothing and sets no exit code; invoke_project() returns the summary. A pipeline built on the PowerShell or Python module that should go red on a failed test does one of two things: let the publish step fail on test failures (Azure DevOps failTaskOnFailedTests, Jenkins’ JUnit plugin, the GitHub publish action), or read the summary itself — Get-CatTestResultSummary / the returned summary in Python / the JSON output’s failedCount and errorCount — and exit non-zero. A CLI step followed by a publish step needs the platform’s always-run guard on the publish step (condition: always() on Azure Pipelines, if: always() on GitHub Actions, when: always on GitLab, a post block on Jenkins), because a red step skips what follows it. A non-zero exit code from CAT otherwise means the run did not complete: the project could not be opened, or the sign-in and plan check refused it — see the tool’s exit codes.

Platform guides #

Step by step, with screenshots:

• CAT in Azure DevOps Pipelines · Azure DevOps Classic Releases
• CAT in GitLab
• CAT in GitHub Actions
• CAT in Jenkins
• SQL Server Agent · CAT in Databricks notebooks · CAT and Microsoft Fabric

Every other platform that can run a shell command works the same way; the guides are starting points, not finished pipelines.