Skip to main content
Use Tusk Drift as API tests in your CI/CD pipeline by running your test suite against commits in your pull requests (PRs). Tusk Drift Cloud offers storage of these tests alongside an additional layer of intelligence on deviations detected:
  • 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

1

Create an account

Create a Tusk account at https://app.usetusk.ai.
2

Connect your repository

Go to the Repositories page on the sidebar and connect the GitHub or GitLab code repository with the service you wish to set up Tusk Drift for.
3

Get your API key

Click on the Settings > API Keys and create a Tusk API key.

​
Configuration

Haven’t set up a Tusk Drift config? Install our CLI first.
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: Please contact support@usetusk.ai to set this up. We’re working on a wizard to enable you to set this up yourself.
  • 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. If set to false , it will export traces to your machine’s filesystem. For deployed services, set this to true.
  • 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

With a sampling rate of 0.01, expect to see a ~6.4% 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.