Tusk Drift GitHub Action

Run Tusk Drift trace tests in GitHub Actions.

New to Tusk Drift? Check out our main page or docs.

What this action does

• Installs the Tusk CLI (tusk) with https://cli.usetusk.ai/install.sh.
• Can optionally build the CLI from a GitHub repo/ref (for unreleased dogfooding).
• Restores and saves Tusk cache data (optional).
• Runs a configurable Tusk command (defaults to CI cloud validation mode).
• Ensures Linux sandbox prerequisites for strict replay runs, including automatic repair on GitHub-hosted runners when bubblewrap user-namespace preflight fails.
• Optionally injects TUSK_API_KEY from an input.

Quick usage

name: Tusk Drift

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  tusk-drift:
    runs-on: ubuntu-latest
    if: github.event_name == 'push' || github.event.pull_request.draft == false

    steps:
      - uses: actions/checkout@v4

      # Any project-specific setup steps go here, for example:
      # - build Docker image
      # - install dependencies
      # - copy env files

      - name: Run Tusk Drift
        uses: Use-Tusk/drift-action@v1
        with:
          working-directory: .
          cache-key:
            ${{ runner.os }}-tusk-drift-${{ hashFiles('.tusk/config.yaml') }}
          api-key: ${{ secrets.TUSK_API_KEY }}

Inputs

Input	Required	Default	Description
working-directory	No	.	Directory where install and run commands execute.
cli-source	No	release	Install source mode: release or source.
install-script-url	No	https://cli.usetusk.ai/install.sh	Install script URL for Tusk CLI. Only used if cli-source is release.
cli-version	No	Latest available CLI version	Specific CLI version to install (for example v1.2.3). Only used if cli-source is release.
cli-source-ref	No	main	Git ref to build from when cli-source is source.
cache	No	true	Restore and save cache for Tusk data.
cache-path	No	~/.cache/tusk	Cache directory path.
cache-key	No	${RUNNER_OS}-tusk-drift	Cache key for restore/save.
cache-restore-keys	No	None	Newline-delimited fallback cache keys.
run-command	No	tusk run -c -p --ci --validate-suite-if-default-branch	Command to execute Tusk Drift tests.
api-key	No	None	Passed as TUSK_API_KEY for the run command. Required for cloud runs.

Outputs

Output	Description
tusk-version	Version returned by tusk --version.
cache-hit	true when cache restored with an exact key match; otherwise false.

Notes

• The action adds ~/.local/bin and /usr/local/bin to PATH.

• If your job should skip cache handling, set cache: false.

• If you run trace tests in Tusk Drift Cloud, provide api-key (or set TUSK_API_KEY in the job environment). Without it, authenticated cloud API calls will fail.

• On Linux, the action verifies that bubblewrap can create user namespaces for Fence sandboxing. On GitHub-hosted runners it will try to repair common CI prerequisites (such as uidmap, /etc/subuid and /etc/subgid, and the bwrap setuid bit) when that preflight fails. On self-hosted runners, it warns instead of mutating system sandbox settings automatically. Docker's userns-remap doc explains how this works.

• If you are installing the CLI from source (cli-source: source), it will use whatever Go version is already on the runner's PATH at runtime. For deterministic builds (or if you hit Go-version issues), pin Go before running this action:

  - uses: actions/setup-go@v5
    with:
      go-version: '1.25' # or the current Go version required by tusk-cli

Contact

Need help? Raise an issue or drop us an email at support@usetusk.ai.