Skip to main content
Use Tusk Drift’s API tests in your CI/CD pipeline by running your test suite against commits in your pull requests (PRs). Our Cloud offering provides storage of these tests alongside an additional layer of intelligence on deviations detected. Key features:
  • Automatic recording of traces based on live traffic in your environment of choice
  • Securely store and maintain these traces as API test suites
  • Analyze deviations (classification of intended vs. unintended deviations), determine root cause of deviations against your code changes, and suggest fixes

​
Getting Started

Haven’t set up a Tusk Drift config? Start by following this guide.
1

Verify Tusk Drift config

Ensure you have set up the essential Tusk Drift config and verified that recording and replaying traces work locally for your service.
2

Run `tusk init-cloud` in CLI

Run tusk init-cloud and follow the setup wizard. It will guide you to:
  1. Authorize the Tusk app for your code hosting service
  2. Register your service for Tusk Drift Cloud
  3. Obtain an API key to use Tusk Drift in CI/CD pipelines
3

Upgrade organization plan

To get Tusk’s AI-powered deviation analysis and suggested fixes, upgrade your account to the Business, Enterprise, or Tusk Drift plan. See plan details.

​
Configuration

service:
	id: <your-service-id>
  ... (other service parameters) ...
  
tusk_api:
	url: "https://api.usetusk.ai"
	
recording:
	sampling_rate: 0.1
	export_spans: true
	enable_env_var_recording: true
	
... (other config parameters) ...
For Tusk Drift Cloud, you’ll need to ensure these parameters are present in your .tusk/config.yaml:
  • service.id: Automatically created once you complete the tusk init-cloud setup wizard.
  • tusk_api.url: Required for exporting traces and test results to Tusk.
  • recording.sampling_rate: The fraction of live requests to record (a value between 0 and 1). Higher values improve fidelity but adds more overhead on your service. We recommend setting a value between 0.01 - 0.1.
  • recording.export_spans: Whether to export recorded traffic to Tusk. For deployed services, set this to true. If set to false , it will export traces to your machine’s filesystem.
  • recording.enable_env_var_recording: Whether to record and replay environment variables. We recommend setting this to true for accurate replay behavior if your service’s logic depends on environment variables.
See the full configuration reference. Once you obtain your Tusk API key, set this as an environment variable (TUSK_API_KEY) in your machine. You may also wish to add this as a GitHub secret so that GitHub Actions workflows can access it securely (see below for an example).

​
Running Tusk Drift in Your CI/CD Pipeline

  • GitHub Actions
Here’s an example of GitHub Actions workflow. Adapt accordingly for your service.
name: Tusk Drift

on:
  pull_request:
    paths:
      - "backend/**"

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

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set Node.js v22
        uses: actions/setup-node@v4
        with:
          node-version: 22.16.0

      - name: Install dependencies
        run: npm ci
        working-directory: ./backend

      - name: Install Tusk Drift CLI
        # This assumes that /usr/local/bin is in the PATH (generally the case on GitHub Actions runners)
        # If not, we can add it to the PATH by running:
        # echo "$HOME/.local/bin" >> $GITHUB_PATH
        run: |
          curl -fsSL https://raw.githubusercontent.com/Use-Tusk/tusk-drift-cli/main/install.sh | sh
          tusk --version

      - name: Run Tusk Drift trace tests
        # CLI automatically picks up commit SHA, PR number, branch name,
        # and external check run ID from CI environment variables.
        run: |
          tusk run -c -p --ci
        working-directory: ./backend
        env:
          TUSK_API_KEY: ${{ secrets.TUSK_API_KEY }}
tusk run crash-course:
  • -c : Load tests from Tusk Drift Cloud
  • -p : Print mode (non-interactive)
  • --ci : Create a Tusk Drift run and upload results to Tusk Drift Cloud
For the full list of options, refer to tusk run --help.

​
Deviation Analysis

When replayed against past recordings, your code change could yield intended deviations (this is good since existing behavior is modified as expected) or unintended deviations (unexpected regressions or bugs). A Tusk Drift run in a CI/CD environment (if the --ci flag is present) exports test results and commit information to Tusk. For each test with a deviation, Tusk correlates the deviation with code changes and performs an analysis, classifying whether it is likely intended/unintended. If it is unintended, Tusk will provide a root cause analysis and suggest fixes. A PR/MR with unintended deviations will have a “Failed” status and may be blocked from merging. Example API Drift Run page in dark mode You will also see a PR/MR comment with an overview of this analysis. Tusk Drift PR comment in GitHub UI If you find that Tusk’s classification is inaccurate, you can manually override it. This serves as feedback to improve future classifications and analyses. Mark as intended modal in API Drift Run page in dark mode If a PR/MR has deviations (whether intended or not) and is merged, the tests corresponding to these deviations will be removed from the test suite as they will no longer be valid.

​
FAQs

Expect a 1-2% throughput overhead. Transforms result in a 1.0% increase in tail latency when a small number of transforms are registered; its impact scales linearly with the number of transforms registered. For more details, see our performance benchmarks.If TUSK_DRIFT_MODE is set to DISABLED or left unset, there is zero performance impact.
Tusk intelligently selects up to 10 unique requests for each endpoint, prioritizing the most diverse ones to ensure comprehensive test coverage. A maximum of 200 unique endpoints are stored for your test suite.
Depending on your traffic volume, you may need to wait for Tusk to replenish tests for these APIs. You also may wish to manually make requests to your service to trigger recordings.