Tusk Drift Cloud Integration
Relevant source files
The following files were used as context for generating this wiki page:Tusk Drift Cloud extends the local record-and-replay capabilities of the CLI by providing a centralized platform for test storage, intelligent deviation analysis, and automated trace recording from live environments. This integration is essential for using Tusk Drift within a CI/CD pipeline to run regression tests against pull requests.
The CLI offers two primary methods for configuring this integration: an interactive TUI wizard via tusk cloud-init and an AI-powered agent via tusk exp init. Both methods guide the user through authentication, repository connection, service registration, and configuration.
Sources: README.md
Onboarding and Setup
There are two main workflows for setting up Tusk Drift Cloud: a guided TUI wizard and an AI-powered agent.
tusk cloud-init Wizard
This interactive terminal UI (TUI) provides a step-by-step process for configuring cloud integration. It is initiated by running tusk cloud-init.
Sources: README.md, internal/tui/onboard-cloud/steps.go
The diagram below illustrates the sequence of steps in the cloud-init wizard.
This flowchart shows the user journey through the tusk cloud-init command.
Sources: internal/tui/onboard-cloud/steps.go:420-435
Key steps include:
- Authentication: Ensures the user is logged into Tusk Cloud.
- Repository Detection: Identifies the local Git repository and its remote URL.
- Organization Selection: Prompts the user to select a Tusk Cloud organization if they belong to multiple.
- Repository Access Verification: Checks if the Tusk GitHub/GitLab app has access to the repository.
- Service Creation: Registers the repository as an "observable service" in Tusk Cloud.
- API Key Creation: Generates an API key for use in CI/CD environments.
- Recording Configuration: Sets parameters for how traces are recorded and exported.
Sources: internal/tui/onboard-cloud/steps.go
AI-Powered Setup (tusk exp init)
The AI agent, initiated with tusk exp init, can also handle cloud setup. After completing the local configuration, the agent prompts the user to continue with cloud integration. If the user agrees, the agent proceeds through a series of cloud-specific phases.
Sources: internal/agent/agent.go:343-350, internal/agent/phases.go:275-286
The diagram below shows the AI agent's cloud setup phases.
This flowchart outlines the phases the AI agent executes for cloud setup.
Sources: internal/agent/phases.go:493-504
The agent uses a specialized set of tools to interact with the Tusk Cloud API and the local environment.
| Tool Name | Description |
|---|---|
cloud_check_auth | Check if the user is already authenticated with Tusk Cloud. |
cloud_login | Initiate the device code login flow. |
cloud_wait_for_login | Wait for the device code authentication to complete. |
cloud_get_clients | Get the list of organizations/clients the user belongs to. |
cloud_select_client | Select and save the organization/client to use. |
cloud_detect_git_repo | Detect the Git repository information from the current directory. |
cloud_verify_repo_access | Verify that Tusk has access to the GitHub/GitLab repository. |
cloud_create_service | Create an observable service in Tusk Cloud for the repository. |
cloud_create_api_key | Create a new API key for CI/CD authentication. |
cloud_save_config | Save cloud configuration to .tusk/config.yaml. |
Sources: internal/agent/executor.go:271-419
Authentication
Authentication is the first step for any cloud interaction. The CLI uses an OAuth 2.0 Device Authorization Grant flow (device code flow).
Sources: internal/tui/onboard-cloud/run.go:121-133
The following sequence diagram illustrates the authentication process.
This diagram shows the device code authentication flow used by the CLI.
Sources: internal/tui/onboard-cloud/run.go:121-133, internal/agent/executor.go:300-306
The ensureAuthenticated function in the onboard-cloud package orchestrates this flow, first attempting to use existing credentials before initiating a new login. The AI agent uses the cloud_login and cloud_wait_for_login tools for the same purpose.
Sources: internal/tui/onboard-cloud/run.go:112-136, internal/agent/executor.go:300-312
Cloud Configuration
Cloud integration settings are stored in the .tusk/config.yaml file alongside local configuration. The setup wizards automatically add or update these fields.
Sources: internal/tui/onboard/config.go:18-49, internal/tui/onboard-cloud/steps.go:285-300
The primary cloud-related settings are under the service and recording keys.
| Path | Type | Description |
|---|---|---|
service.id | string | The unique identifier for the observable service in Tusk Cloud. |
recording.sampling_rate | float64 | The percentage of requests to record (e.g., 0.1 for 10%). |
recording.export_spans | boolean | If true, recorded traces (spans) are uploaded to Tusk Cloud. |
recording.enable_env_var_recording | boolean | If true, environment variables are recorded with traces. |
tusk_api.url | string | The base URL for the Tusk Cloud API. |
Sources: internal/tui/onboard/config.go:22-49, internal/tui/onboard-cloud/steps.go:291-295
A typical config.yaml with cloud settings might look like this:
# Tusk Drift configuration
# For all configuration options, see:
# https://github.com/Use-Tusk/tusk-drift-cli/blob/main/docs/configuration.md
service:
id: "svc-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
name: my-service
port: 3000
# ... other service settings
recording:
sampling_rate: 0.1
export_spans: true
enable_env_var_recording: true
tusk_api:
url: https://api.usetusk.ai
# ... other settings
Sources: internal/tui/onboard/config.go:18-49, 142-146
Cloud-Enabled Commands
Once configured, you can interact with Tusk Drift Cloud using specific flags on existing commands.
tusk list --cloud: Lists test suites that have been recorded and stored in Tusk Drift Cloud for the configured service.tusk run --cloud: Fetches test suites from the cloud and runs them locally against your service, providing a way to execute cloud-managed tests in any environment.
Sources: README.md
Setup Summary and Reporting
Both setup methods conclude by providing the user with a summary of what was configured and what the next steps are.
The tusk cloud-init wizard presents a ReviewStep that lists the detected repository, the new Service ID, API key status, and the chosen recording configuration.
Sources: internal/tui/onboard-cloud/steps.go:312-351
The AI agent's cloud_summary phase generates a similar report in markdown format, which is displayed in the terminal and saved to .tusk/CLOUD_SETUP_REPORT.md. This report includes:
- Configuration summary (repository, Service ID, sampling rate, etc.).
- API key status.
- Actionable next steps for the user, such as pushing changes and running cloud commands.
- Useful links to the Tusk application dashboard and documentation.
Sources: internal/agent/prompts/phase_cloud_summary.md
Conclusion
Tusk Drift Cloud Integration bridges the gap between local development testing and robust CI/CD validation. By connecting the CLI to the cloud platform, developers can leverage centralized test storage, automated recording from live traffic, and intelligent analysis of test results. The tusk cloud-init wizard and the tusk exp init AI agent provide flexible and powerful pathways to enable this integration, ultimately facilitating a more reliable and efficient testing workflow.
Sources: README.md, internal/agent/prompts/phase_cloud_summary.md