Skip to main content
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 installs the Tusk Drift CLI and runs your tests on every pull request.

​
Prerequisites

Before setting up Tusk Drift in CI/CD, ensure you have:
  • Completed local setup with recording and replay working
  • Completed tusk init-cloud setup wizard
  • Obtained your Tusk API key

​
Quick Start

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

​
Complete Workflow Example

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. Install Tusk Drift CLI
      - name: Install Tusk Drift CLI
        run: |
          curl -fsSL https://cli.usetusk.ai/install.sh | sh
          tusk --version

      # 5. Run Tusk Drift tests
      # The CLI automatically detects commit SHA, PR number, and branch
      # from GitHub Actions environment variables
      - name: Run Tusk Drift trace tests
        run: tusk run -c -p --ci --validate-suite-if-default-branch
        working-directory: ./backend
        env:
          TUSK_API_KEY: ${{ secrets.TUSK_API_KEY }}
The Tusk CLI automatically starts your service using the command defined in .tusk/config.yaml. Your CI workflow just needs to ensure all dependencies are installed beforehand (e.g., npm ci, database migrations, 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:
  • 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
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: 
on:
  pull_request:
    paths:
      - "backend/**"       # Your service directory
      - ".tusk/**"         # Tusk configuration

​
CLI Flags Reference

​
Common Flags for CI

FlagDescription
-c, --cloudLoad tests from Tusk Drift Cloud instead of local .tusk/traces
-p, --printNon-interactive output mode (required for CI environments)
--ciCreate a Tusk Drift run and upload results to Cloud
--validate-suite-if-default-branchOn default branch, validate and promote draft tests to the suite
--enable-service-logsSave service logs to .tusk/logs, helpful while debugging
For the full list of options, run tusk run --help.

​
Environment Variables

​
Required

VariableDescription
TUSK_API_KEYAPI key for Tusk Drift Cloud authentication. Add this to your CI secrets.

​
Auto-Detected Variables

The CLI automatically detects these from your CI environment:
  • 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

​
Troubleshooting

If tests remain in “Draft” and aren’t moving to “In Suite”:
  1. Ensure your workflow triggers on push to the default branch (e.g., main)
  2. Verify --validate-suite-if-default-branch flag is included
  3. Check that tests pass on the default branch
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)