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
tusk init-cloudsetup wizard - Obtained your Tusk API key
Quick Start
- Add
TUSK_API_KEYto your repository secrets (GitHub) or CI/CD variables (GitLab) - Create a workflow file:
- GitHub:
.github/workflows/tusk-drift.yml - GitLab:
.gitlab-ci.yml
- GitHub:
- Configure it to run tests:
- GitHub: use
Use-Tusk/drift-action - GitLab: install the CLI and run
tusk rundirectly (see full examples below)
- GitHub: use
Complete Workflow Example
- GitHub Actions
- GitLab CI
- Other CI providers
Create
.github/workflows/tusk-drift.yml: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 -pushto main: Required for--validate-suite-if-default-branchto promote passing draft tests to the suite
Path Filtering
Use path filtering to only run Tusk Drift when relevant files change:- GitHub Actions
- GitLab CI
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 |
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
tusk run command:
--commit-sha, --pr-number, --branch, and optionally
--external-check-run-id.
Troubleshooting
My draft tests are not being promoted
My draft tests are not being promoted
If tests remain in “Draft” and aren’t moving to “In Suite”:
- Ensure your workflow triggers on
pushto the default branch (e.g.,main) - Verify
--validate-suite-if-default-branchflag is included - Check that tests pass on the default branch
My service won't start in CI
My service won't start in CI
Check for these gotchas:
- Ensure you have completed local setup with recording and replay working
- Verify
working-directorypoints to the correct path - Ensure all dependencies are installed before running
tusk run
--enable-service-logs (saves service/SDK logs to .tusk/logs)