Comprehensive guide for migrating from Jira, Asana, or other issue trackers to Linear, covering assessment, workflow mapping, data export, transformation, batch import, validation, and post-migration reporting.
Complete the assessment checklist: data volume (issues, projects, users, attachments, custom fields), workflow analysis (statuses, transitions, automations, integrations), user mapping (source to Linear users), and timeline (migration window, parallel run period, cutover date, rollback deadline).
Define status, priority, and issue type mappings for each source system. Jira statuses map to Linear states (e.g., "To Do" -> "Todo", "In Progress" -> "In Progress", "Blocked" -> "In Progress" with label). Jira priorities map to Linear 1-4 scale. Jira issue types become Linear labels. Asana sections map similarly to Linear states.
Build exporters for each source: exportJiraProject() using JQL with pagination (100 per page), fetching summary, description, status, priority, type, assignee, labels, story points, and parent/subtask relations. exportAsanaProject() using the Asana SDK to fetch tasks with section names, tags, assignees, and hierarchy. Save exports as timestamped JSON backups.
Create transformJiraIssue() that maps each source issue to LinearIssueInput: resolve status to stateId, priority to number, assignee email to Linear userId, issue type and labels to labelIds, story points to estimate, and convert Jira markup to Markdown (headers, bold/italic, code blocks, lists, links).
Build importToLinear() that sorts issues by hierarchy (parents first), checks for duplicates, transforms each issue, sets parentId for subtasks, creates via linearClient.createIssue(), tracks the sourceId-to-linearId mapping, and respects rate limits (100ms between requests). Track stats: total, created, skipped, errors.
Run validateMigration() to verify all issues were imported, then sample 50 issues to check title, priority, and state mappings. Generate a migration report with statistics, ID mapping table, and error list. Follow the post-migration checklist: verify critical issues, update integrations, archive source after parallel run, train team.
See detailed implementation for complete Jira/Asana exporters, data transformer with Jira-to-Markdown converter, batch importer with hierarchy sorting, validation script, and migration report generator.
| Issue | Cause | Solution |
|---|---|---|
| User not found | Unmapped user | Add to user mapping |
| Rate limited | Too fast import | Add delays between requests |
| State not found | Unmapped status | Update state mapping |
| Parent not found | Import order wrong | Sort by hierarchy first |
Basic usage: Apply linear migration deep dive to a standard project setup with default configuration options.
Advanced scenario: Customize linear migration deep dive for production environments with multiple constraints and team-specific requirements.
You have completed the Linear Flagship Skill Pack. You now have comprehensive knowledge of Linear integrations from basic setup through enterprise deployment.
