rudder-import-and-evolve

Name: rudder-import-and-evolve
Author: rudderlabs

18stars0forks

How to install rudder-import-and-evolve?

rudderlabs/rudder-agent-skills/rudder-import-and-evolve

$npx -y skills add rudderlabs/rudder-agent-skills --skill rudder-import-and-evolve

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# Import and Evolve Workflow
2
3	This skill teaches how to import existing RudderStack resources into CLI management and safely evolve your tracking schema over time.
4
5	## When to Use This Skill
6
7	- You have existing tracking plans, events, or properties in RudderStack
8	- You want to manage them via YAML files and git
9	- You need to make changes without breaking production SDKs
10	- You're migrating from UI-based management to CLI
11
12	## Import Workflow
13
14	```
15	┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
16	│ RudderStack │────▶│ Import to │────▶│ Local YAML │
17	│ Workspace │ │ Local Files │ │ Files │
18	└─────────────────┘ └─────────────────┘ └─────────────────┘
19	│
20	▼
21	┌─────────────────┐
22	│ Git Version │
23	│ Control │
24	└─────────────────┘
25	```
26
27	### Step 1: Authenticate
28
29	```bash
30	rudder-cli auth login
31	```
32
33	Select your workspace when prompted.
34
35	### Step 2: Verify Connection
36
37	```bash
38	rudder-cli workspace info
39	```
40
41	Should show your workspace name and ID.
42
43	### Step 3: Import Resources
44
45	```bash
46	rudder-cli import workspace
47	```
48
49	This imports:
50	- Events
51	- Properties
52	- Categories
53	- Custom types
54	- Tracking plans
55	- Event stream sources (if applicable)
56	- Transformations and libraries
57
58	### Step 4: Review Imported Files
59
60	```
61	imported/
62	├── data-catalog/
63	│ ├── events/
64	│ │ └── *.yaml
65	│ ├── properties/
66	│ │ └── *.yaml
67	│ ├── categories/
68	│ │ └── *.yaml
69	│ └── custom-types/
70	│ └── *.yaml
71	└── tracking-plans/
72	└── *.yaml
73	```
74
75	Each file includes import metadata:
76
77	```yaml
78	version: "rudder/v1"
79	kind: "event"
80	metadata:
81	name: "events"
82	import:
83	id: "evt_abc123xyz" # Links to workspace resource
84	workspace: "ws_xyz789"
85	spec:
86	name: "Product Viewed"
87	# ... rest of spec
88	```
89
90	Important: The `metadata.import` section links local files to workspace resources. Don't modify these IDs.
91
92	## Safe Evolution Patterns
93
94	See `references/evolution-patterns.md` for detailed patterns including:
95	- Adding new properties (start optional)
96	- Making properties required (phased approach via tracking plans)
97	- Renaming events (parallel events during transition)
98	- Deprecating events (notice period, then remove)
99	- Adding custom types to existing properties
100	- Multi-workspace management (dev/staging/production)
101
102	## Handling Import Drift
103
104	Problem: Someone made changes in the UI after import.
105
106	Solution 1: Re-import (overwrites local)
107
108	```bash
109	# Warning: This overwrites your local changes!
110	rudder-cli import workspace --force
111	```
112
113	Solution 2: Manual reconciliation
114
115	```bash
116	# 1. Compare local vs workspace
117	rudder-cli apply --dry-run -l ./
118
119	# 2. Review differences
120	# "Updated" means local differs from workspace
121	# Decide: use local (apply) or use workspace (re-import that file)
122
123	# 3. Apply your version
124	rudder-cli apply -l ./
125	```
126
127	Best practice: After import, all changes go through CLI. Disable UI editing for data catalog if possible.
128
129	## Import Gotchas
130
131	### Pull is Not Supported
132
133	Import is a one-time snapshot. There's no `rudder-cli pull` to sync changes from workspace.
134
135	```bash
136	# This doesn't exist:
137	rudder-cli pull # ❌ Not a command
138
139	# Instead, re-import to get latest:
140	rudder-cli import workspace # Overwrites local
141	```
142
143	### Import Metadata Must Match
144
145	If you copy files between workspaces, update the `metadata.import` section:
146
147	```yaml
148	# Wrong: IDs from different workspace
149	metadata:
150	import:
151	id: "evt_from_other_workspace"
152	workspace: "ws_different"
153
154	# Right: Remove import metadata for new workspace
155	metadata:
156	name: "events"
157	# No import section - will create new resource
158	```
159
160	### Partial Import Creates Orphans
161
162	If you import, delete some files, then apply:
163
164	```bash
165	# This will DELETE resources from workspace!
166	rudder-cli apply -l ./ # Shows "Deleted [event] ..."
167	```
168
169	The CLI tracks what was imported. Missing files = deletions.
170
171	## CLI Commands Reference
172
173	```bash
174	# Authenticate
175	rudder-cli auth login
176
177	# Show current workspace
178	rudder-cli workspace info
179
180	# Import all resources
181	rudder-cli import workspace
182
183	# Import specific resource types
184	rudder-cli import workspace --resources events,properties
185
186	# Validate imported files
187	rudder-cli validate -l ./
188
189	# Preview changes
190	rudder-cli apply --dry-run -l ./
191
192	# Apply changes
193	rudder-cli apply -l ./
194	```
195
196	## Handling External Content
197
198	When importing resources from RudderStack workspace:
199
200	- Review imported YAML - verif

People who liked this also viewed

6 picks

Type

rudder-import-and-evolve

18stars0forks

View on GitHub

How to install rudder-import-and-evolve?

rudderlabs/rudder-agent-skills/rudder-import-and-evolve

$npx -y skills add rudderlabs/rudder-agent-skills --skill rudder-import-and-evolve

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# Import and Evolve Workflow
2
3	This skill teaches how to import existing RudderStack resources into CLI management and safely evolve your tracking schema over time.
4
5	## When to Use This Skill
6
7	- You have existing tracking plans, events, or properties in RudderStack
8	- You want to manage them via YAML files and git
9	- You need to make changes without breaking production SDKs
10	- You're migrating from UI-based management to CLI
11
12	## Import Workflow
13
14	```
15	┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
16	│ RudderStack │────▶│ Import to │────▶│ Local YAML │
17	│ Workspace │ │ Local Files │ │ Files │
18	└─────────────────┘ └─────────────────┘ └─────────────────┘
19	│
20	▼
21	┌─────────────────┐
22	│ Git Version │
23	│ Control │
24	└─────────────────┘
25	```
26
27	### Step 1: Authenticate
28
29	```bash
30	rudder-cli auth login
31	```
32
33	Select your workspace when prompted.
34
35	### Step 2: Verify Connection
36
37	```bash
38	rudder-cli workspace info
39	```
40
41	Should show your workspace name and ID.
42
43	### Step 3: Import Resources
44
45	```bash
46	rudder-cli import workspace
47	```
48
49	This imports:
50	- Events
51	- Properties
52	- Categories
53	- Custom types
54	- Tracking plans
55	- Event stream sources (if applicable)
56	- Transformations and libraries
57
58	### Step 4: Review Imported Files
59
60	```
61	imported/
62	├── data-catalog/
63	│ ├── events/
64	│ │ └── *.yaml
65	│ ├── properties/
66	│ │ └── *.yaml
67	│ ├── categories/
68	│ │ └── *.yaml
69	│ └── custom-types/
70	│ └── *.yaml
71	└── tracking-plans/
72	└── *.yaml
73	```
74
75	Each file includes import metadata:
76
77	```yaml
78	version: "rudder/v1"
79	kind: "event"
80	metadata:
81	name: "events"
82	import:
83	id: "evt_abc123xyz" # Links to workspace resource
84	workspace: "ws_xyz789"
85	spec:
86	name: "Product Viewed"
87	# ... rest of spec
88	```
89
90	Important: The `metadata.import` section links local files to workspace resources. Don't modify these IDs.
91
92	## Safe Evolution Patterns
93
94	See `references/evolution-patterns.md` for detailed patterns including:
95	- Adding new properties (start optional)
96	- Making properties required (phased approach via tracking plans)
97	- Renaming events (parallel events during transition)
98	- Deprecating events (notice period, then remove)
99	- Adding custom types to existing properties
100	- Multi-workspace management (dev/staging/production)
101
102	## Handling Import Drift
103
104	Problem: Someone made changes in the UI after import.
105
106	Solution 1: Re-import (overwrites local)
107
108	```bash
109	# Warning: This overwrites your local changes!
110	rudder-cli import workspace --force
111	```
112
113	Solution 2: Manual reconciliation
114
115	```bash
116	# 1. Compare local vs workspace
117	rudder-cli apply --dry-run -l ./
118
119	# 2. Review differences
120	# "Updated" means local differs from workspace
121	# Decide: use local (apply) or use workspace (re-import that file)
122
123	# 3. Apply your version
124	rudder-cli apply -l ./
125	```
126
127	Best practice: After import, all changes go through CLI. Disable UI editing for data catalog if possible.
128
129	## Import Gotchas
130
131	### Pull is Not Supported
132
133	Import is a one-time snapshot. There's no `rudder-cli pull` to sync changes from workspace.
134
135	```bash
136	# This doesn't exist:
137	rudder-cli pull # ❌ Not a command
138
139	# Instead, re-import to get latest:
140	rudder-cli import workspace # Overwrites local
141	```
142
143	### Import Metadata Must Match
144
145	If you copy files between workspaces, update the `metadata.import` section:
146
147	```yaml
148	# Wrong: IDs from different workspace
149	metadata:
150	import:
151	id: "evt_from_other_workspace"
152	workspace: "ws_different"
153
154	# Right: Remove import metadata for new workspace
155	metadata:
156	name: "events"
157	# No import section - will create new resource
158	```
159
160	### Partial Import Creates Orphans
161
162	If you import, delete some files, then apply:
163
164	```bash
165	# This will DELETE resources from workspace!
166	rudder-cli apply -l ./ # Shows "Deleted [event] ..."
167	```
168
169	The CLI tracks what was imported. Missing files = deletions.
170
171	## CLI Commands Reference
172
173	```bash
174	# Authenticate
175	rudder-cli auth login
176
177	# Show current workspace
178	rudder-cli workspace info
179
180	# Import all resources
181	rudder-cli import workspace
182
183	# Import specific resource types
184	rudder-cli import workspace --resources events,properties
185
186	# Validate imported files
187	rudder-cli validate -l ./
188
189	# Preview changes
190	rudder-cli apply --dry-run -l ./
191
192	# Apply changes
193	rudder-cli apply -l ./
194	```
195
196	## Handling External Content
197
198	When importing resources from RudderStack workspace:
199
200	- Review imported YAML - verif

People who liked this also viewed

6 picks

Type