supported
Linear imports
Linear workspace exports are treated as a first-class migration source for projects, issues, labels, statuses, users, comments, and attachments.
Formats: Linear, CSV, JSON
Migration guide
Import/export migration guide.
Move planning data into and out of buildr-plannr with dry-run previews, explicit mapping rules, validation errors, rollback evidence, and export retention. The guide covers Linear, CSV, JSON, and future provider assumptions for human and agent-ready work.
Import and export guide summary
Sources
4
Mapping rules
8
Workflow stages
6
Export formats
4
Source assumptions
Linear, CSV, JSON, and future providers all start with preview.
Imports should never mutate workspace data until mapping, validation, entitlement, and recovery evidence are visible.
supported
CSV imports
CSV is the lowest-friction path for issue lists, labels, owners, statuses, priorities, and simple dependency columns.
Formats: CSV
supported
JSON imports and exports
JSON is the canonical loss-minimizing format for buildr-plannr backups, agent task contracts, context references, dependencies, and evidence.
Formats: JSON, backup
planned
Future provider imports
Future connectors follow the same mapping contract: preview first, validate ownership and limits, then commit with audit evidence.
Formats: GitHub, Jira CSV, Markdown, Notion
Mapping rules
Projects, issues, features, labels, statuses, users, comments, and attachments need explicit targets.
| Target | Import rule | Export rule | Validation rule |
|---|---|---|---|
| Projects | Source projects map to buildr-plannr projects by stable ID when present, then normalized name. Missing projects block commit. | Exports include project IDs and names so downstream systems can preserve workspace structure. | Dry runs report missing project IDs, name collisions, and workspace mismatches. |
| Issues | Issues map by stable source ID first, then title within project. Existing issues are updated only when the preview shows changed fields. | Exports include title, description, status, priority, dependencies, agent instructions, acceptance checks, and verification evidence. | Dry runs classify each row as create, update, unchanged, conflict, or error. |
| Features | Feature records map to project milestones, labels, or parent issues until a dedicated feature object is available. | Exports preserve feature-like grouping through project, milestone, label, and dependency fields. | Unmapped feature fields must be reviewed before commit so agent work does not lose product intent. |
| Labels | Labels are normalized by lowercase name within the workspace and merged when they differ only by spacing or case. | Exports include labels as readable names rather than internal-only identifiers. | Dry runs flag conflicting label meanings and unsupported label groups. |
| Statuses | Source statuses map into the target workflow by configured status names, then by category such as backlog, todo, in progress, done, or canceled. | Exports include the current status name and preserve active versus completed meaning. | Unknown statuses block commit until a target status or fallback category is selected. |
| Users | Users map by verified email where available; otherwise they are preserved as external authors until invited. | Exports avoid secrets and include only safe assignee or author references needed for migration. | Dry runs identify unresolved owners and never create active members without workspace admin approval. |
| Comments | Comments keep author display name, created date, body, and source ID when available. Private comments require explicit inclusion. | Exports preserve comment order and redact secrets according to workspace policy. | Dry runs flag oversized comments, unsupported markdown, and comments with blocked attachments. |
| Attachments | Attachments import only from allowed URLs or uploaded archives after size, type, malware, and ownership checks pass. | Exports include attachment metadata and references; binary payload export is handled by plan-gated backup paths. | Dry runs block inaccessible, oversized, suspicious, or cross-workspace attachment references. |
Migration workflow
Dry runs, errors, rollback, and retention are part of the product contract.
Source inventory
Confirm source system, export format, record counts, owner mapping, attachment scope, and plan limits before upload.
Evidence: Source export checksum, Expected project and issue counts, Owner mapping decision
Dry run preview
Run preview first. The preview shows creates, updates, unchanged rows, conflicts, validation errors, quota impact, and recovery metadata.
Evidence: Preview ID, Idempotency key, Create/update/conflict counts
Validation errors
Resolve row and path errors before commit. Missing workspaces, projects, milestones, unsupported statuses, malformed JSON, and relationship mismatches block commit.
Evidence: Row number, Path-like error, Customer-facing fix instruction
Commit
Commit only an unexpired, unblocked preview. Commit operations are idempotent and report created, updated, skipped, and failed rows.
Evidence: Commit ID, Operation summary, Audit event
Rollback and recovery
Use preview output, source checksums, export snapshots, and audit events to recover from bad mappings without deleting unrelated workspace data.
Evidence: Pre-commit export, Affected issue IDs, Recovery owner
Export retention
Exports are plan-gated artifacts with schema version, filename, size, hash, filters, created date, and retention expectations.
Evidence: Export ID, SHA-256 hash, Retention window
Need help?
Support uses metadata, checksums, row errors, and affected IDs, not raw exports or private issue content.
Keep source checksums, preview IDs, commit IDs, export IDs, and redacted examples available before requesting migration support.