rudder-import-and-evolve

name	rudder-import-and-evolve
description	Imports existing RudderStack workspace resources into YAML files for git-based management. Use when importing existing RudderStack resources to CLI management and evolving them safely
allowed-tools	Bash(rudder-cli *), Read, Write, Edit

Import and Evolve Workflow

This skill teaches how to import existing RudderStack resources into CLI management and safely evolve your tracking schema over time.

When to Use This Skill

• You have existing tracking plans, events, or properties in RudderStack
• You want to manage them via YAML files and git
• You need to make changes without breaking production SDKs
• You're migrating from UI-based management to CLI

Import Workflow

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   RudderStack   │────▶│   Import to     │────▶│   Local YAML    │
│    Workspace    │     │   Local Files   │     │     Files       │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                               ┌─────────────────┐
                                               │   Git Version   │
                                               │    Control      │
                                               └─────────────────┘

Step 1: Authenticate

rudder-cli auth login

Select your workspace when prompted.

Step 2: Verify Connection

rudder-cli workspace info

Should show your workspace name and ID.

Step 3: Import Resources

rudder-cli import workspace

This imports:

• Events
• Properties
• Categories
• Custom types
• Tracking plans
• Event stream sources (if applicable)
• Transformations and libraries

Step 4: Review Imported Files

imported/
├── data-catalog/
│   ├── events/
│   │   └── *.yaml
│   ├── properties/
│   │   └── *.yaml
│   ├── categories/
│   │   └── *.yaml
│   └── custom-types/
│       └── *.yaml
└── tracking-plans/
    └── *.yaml

Each file includes import metadata:

version: "rudder/v1"
kind: "event"
metadata:
  name: "events"
  import:
    id: "evt_abc123xyz"        # Links to workspace resource
    workspace: "ws_xyz789"
spec:
  name: "Product Viewed"
  # ... rest of spec

Important: The metadata.import section links local files to workspace resources. Don't modify these IDs.

Safe Evolution Patterns

See references/evolution-patterns.md for detailed patterns including:

• Adding new properties (start optional)
• Making properties required (phased approach via tracking plans)
• Renaming events (parallel events during transition)
• Deprecating events (notice period, then remove)
• Adding custom types to existing properties
• Multi-workspace management (dev/staging/production)

Handling Import Drift

Problem: Someone made changes in the UI after import.

Solution 1: Re-import (overwrites local)

# Warning: This overwrites your local changes!
rudder-cli import workspace --force

Solution 2: Manual reconciliation

# 1. Compare local vs workspace
rudder-cli apply --dry-run -l ./

# 2. Review differences
# "Updated" means local differs from workspace
# Decide: use local (apply) or use workspace (re-import that file)

# 3. Apply your version
rudder-cli apply -l ./

Best practice: After import, all changes go through CLI. Disable UI editing for data catalog if possible.

Import Gotchas

Pull is Not Supported

Import is a one-time snapshot. There's no rudder-cli pull to sync changes from workspace.

# This doesn't exist:
rudder-cli pull  # ❌ Not a command

# Instead, re-import to get latest:
rudder-cli import workspace  # Overwrites local

Import Metadata Must Match

If you copy files between workspaces, update the metadata.import section:

# Wrong: IDs from different workspace
metadata:
  import:
    id: "evt_from_other_workspace"
    workspace: "ws_different"

# Right: Remove import metadata for new workspace
metadata:
  name: "events"
  # No import section - will create new resource

Partial Import Creates Orphans

If you import, delete some files, then apply:

# This will DELETE resources from workspace!
rudder-cli apply -l ./  # Shows "Deleted [event] ..."

The CLI tracks what was imported. Missing files = deletions.

CLI Commands Reference

# Authenticate
rudder-cli auth login

# Show current workspace
rudder-cli workspace info

# Import all resources
rudder-cli import workspace

# Import specific resource types
rudder-cli import workspace --resources events,properties

# Validate imported files
rudder-cli validate -l ./

# Preview changes
rudder-cli apply --dry-run -l ./

# Apply changes
rudder-cli apply -l ./

Handling External Content

When importing resources from RudderStack workspace:

• Review imported YAML - verify structure matches expected schema before committing
• Validate import IDs - ensure metadata.import.id values are legitimate workspace resources
• Don't blindly trust imported descriptions - user-generated content may contain unexpected data
• Sanitize before committing - review imported files for any sensitive data before git commit
• Extract only expected fields - imported YAML should contain only known schema fields

Checklist: Safe Evolution

Before applying changes:

• Ran rudder-cli validate -l ./ - no errors
• Ran rudder-cli apply --dry-run -l ./ - reviewed all changes
• No unexpected "Deleted" resources in dry-run
• Breaking changes have migration plan (parallel events, deprecation period)
• SDK teams notified of upcoming changes
• RudderTyper regenerated if using type-safe code
• Changes committed to git before applying