CI/CD Setup

Run your Tusk Drift test suite against commits in pull requests to catch API regressions before they reach production. To do this, you’ll create a CI workflow file that runs your tests on every pull request. For GitHub Actions, you can use the Use-Tusk/drift-action action to handle CLI installation and test execution.

Prerequisites

Before setting up Tusk Drift in CI/CD, ensure you have:

Completed local setup with recording and replay working
Completed Cloud setup (i.e., ran tusk drift setup --skip-to-cloud)
Obtained your Tusk API key

Quick Start

Add TUSK_API_KEY to your repository secrets (GitHub) or CI/CD variables (GitLab)
Create a workflow file:
- GitHub: .github/workflows/tusk-drift.yml
- GitLab: .gitlab-ci.yml
Configure it to run tests:
- GitHub: use Use-Tusk/drift-action
- GitLab: install the CLI and run tusk run directly (see full examples below)

Complete Workflow Example

GitHub Actions
GitLab CI
Other CI providers

Create .github/workflows/tusk-drift.yml:

name: Tusk Drift

on:
  pull_request:
    paths:
      - "backend/**"
  # Push to main is required for --validate-suite-if-default-branch
  # to validate and promote draft tests to the suite
  push:
    branches:
      - main

jobs:
  tusk-drift:
    runs-on: ubuntu-latest

    steps:
      # 1. Checkout your repository
      - name: Checkout
        uses: actions/checkout@v4

      # 2. Set up your runtime (Node.js example - adapt for your stack)
      - name: Set Node.js v22
        uses: actions/setup-node@v4
        with:
          node-version: 22.16.0

      # 3. Install dependencies and set up your service
      # Add any steps needed for your service to start successfully:
      # - Install dependencies
      # - Run database migrations
      # - Build/compile your code, etc
      - name: Install dependencies
        run: npm ci
        working-directory: ./backend

      # 4. Run Tusk Drift tests (installs CLI + runs tests)
      # The action internally runs:
      # tusk run -c -p --ci --validate-suite-if-default-branch
      - name: Run Tusk Drift
        uses: Use-Tusk/drift-action@v1
        with:
          working-directory: ./backend
          # GitHub Action cache to load Cloud traces faster
          cache-key: ${{ runner.os }}-tusk-drift-${{ hashFiles('backend/.tusk/config.yaml') }}
          api-key: ${{ secrets.TUSK_API_KEY }}

Add to your .gitlab-ci.yml:

tusk-drift:
  stage: test
  image: node:22

  before_script:
    # 1. Install dependencies and set up your service
    # Add any steps needed for your service to start successfully:
    # - Install dependencies
    # - Run database migrations
    # - Build/compile your code, etc
    - cd backend
    - npm ci

    # 2. Install Tusk Drift CLI
    - curl -fsSL https://cli.usetusk.ai/install.sh | sh
    - tusk --version

  script:
    # 3. Run Tusk Drift tests
    # The CLI automatically detects commit SHA, MR number, and branch
    # from GitLab CI environment variables
    - tusk run -c -p --ci --validate-suite-if-default-branch

  rules:
    # Run on merge requests
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - backend/**
    # Run on pushes to default branch (required for --validate-suite-if-default-branch)
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

  variables:
    TUSK_API_KEY: $TUSK_API_KEY

For CI providers other than GitHub Actions and GitLab CI (for example, CircleCI, Buildkite, Jenkins, Azure DevOps), include these pieces:

Repository checkout
Runtime + service setup, e.g.:
- Install dependencies
- Build/compile your service

Install Tusk CLI:

curl -fsSL https://cli.usetusk.ai/install.sh | sh

Run Tusk in CI mode and pass CI metadata explicitly:

tusk run -c -p --ci --validate-suite-if-default-branch \
  --commit-sha "$CI_COMMIT_SHA" \
  --pr-number "$CI_PR_NUMBER" \
  --branch "$CI_BRANCH_NAME" \
  --external-check-run-id "$CI_CHECK_RUN_ID"

Notes:

--commit-sha, --pr-number, and --branch are required in CI mode if your provider is not auto-detected.
--external-check-run-id is optional but recommended when your provider has a stable job/check identifier.
--pr-number must be a numeric pull/merge request number.
Keep TUSK_API_KEY available as a secret environment variable.

The Tusk CLI automatically starts your service using the command defined in .tusk/config.yaml. In GitHub Actions, Use-Tusk/drift-action handles CLI installation and running tests, but your workflow still needs to ensure service prerequisites are ready beforehand (e.g., npm ci, build steps) so the service can start successfully.

Workflow Triggers Explained

Your workflow should trigger on both pull/merge requests and pushes to the default branch:

GitHub Actions
GitLab CI
Other CI providers

pull_request: Runs tests on PR branches, reports deviations, blocks merging if unintended deviations found - push to main: Required for --validate-suite-if-default-branch to promote passing draft tests to the suite

$CI_PIPELINE_SOURCE == "merge_request_event": Runs tests on MR branches, reports deviations, blocks merging if unintended deviations found
$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH: Required for --validate-suite-if-default-branch to promote passing draft tests to the suite

Pull/merge request pipeline trigger: Runs drift tests on proposed changes.
Push trigger on default branch: Required for --validate-suite-if-default-branch to validate and promote draft tests.

If you only trigger on pull/merge requests, draft tests will never be promoted to your test suite. Always include a trigger for pushes to your default branch.

Path Filtering

Use path filtering to only run Tusk Drift when relevant files change:

GitHub Actions
GitLab CI

on:
  pull_request:
    paths:
      - "backend/**"       # Your service directory
      - ".tusk/**"         # Tusk configuration

rules:
  - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    changes:
      - backend/**         # Your service directory
      - .tusk/**           # Tusk configuration

CLI Flags Reference

Common Flags for CI

Flag	Description
`-c, --cloud`	Load tests from Tusk Drift Cloud instead of local `.tusk/traces`
`-p, --print`	Non-interactive output mode (required for CI environments)
`--ci`	Create a Tusk Drift run and upload results to Cloud
`--validate-suite-if-default-branch`	On default branch, validate and promote draft tests to the suite
`--enable-service-logs`	Save service logs to `.tusk/logs`, helpful while debugging

For the full list of options, run tusk run --help.

Environment Variables

Required

Variable	Description
`TUSK_API_KEY`	API key for Tusk Drift Cloud authentication. Add this to your CI secrets.

Auto-Detected Variables

The CLI auto-detects these in GitHub Actions and GitLab CI:

Commit SHA - from GITHUB_SHA, CI_COMMIT_SHA, etc.
PR/MR number - from GITHUB_REF, CI_MERGE_REQUEST_IID, etc.
Branch name - from GITHUB_HEAD_REF, CI_COMMIT_REF_NAME, etc.
Check run ID - for GitHub status updates

For other CI providers, pass metadata with flags in your tusk run command: --commit-sha, --pr-number, --branch, and optionally --external-check-run-id.

Troubleshooting

My draft tests are not being promoted

If tests remain in “Draft” and aren’t moving to “In Suite”:

Ensure your workflow triggers on push to the default branch (e.g., main)
Verify --validate-suite-if-default-branch flag is included
Check that tests pass on the default branch

My service won't start in CI

Check for these gotchas:

Ensure you have completed local setup with recording and replay working
Verify working-directory points to the correct path
Ensure all dependencies are installed before running tusk run

You can enable service logs for debugging: --enable-service-logs (saves service/SDK logs to .tusk/logs)

Get Started

Platform

Analytics API

CI/CD Setup

Prerequisites

Quick Start

Complete Workflow Example

Workflow Triggers Explained

Path Filtering

CLI Flags Reference

Common Flags for CI

Environment Variables

Required

Auto-Detected Variables

Troubleshooting

​Prerequisites

​Quick Start

​Complete Workflow Example

​Workflow Triggers Explained

​Path Filtering

​CLI Flags Reference

​Common Flags for CI

​Environment Variables

​Required

​Auto-Detected Variables

​Troubleshooting

Prerequisites

Quick Start

Complete Workflow Example

Workflow Triggers Explained

Path Filtering

CLI Flags Reference

Common Flags for CI

Environment Variables

Required

Auto-Detected Variables

Troubleshooting