How to Migrate from Jira to Linear: A Step-by-Step Guide for Engineering Teams

Disclosure: This article contains affiliate links. We may earn a commission if you sign up through one of our links, at no extra cost to you.

TL;DR: Linear’s built-in Jira importer handles the technical migration in under an hour. The real work is the conceptual translation — understanding why Jira’s organizing concepts don’t map to Linear’s in the ways you’d expect — and the mindset shift that makes the migration worth doing. This guide covers both.

---

If you’ve reached this article, your team has decided to leave Jira. This guide won’t re-argue the case — for that, see our Linear vs Jira comparison. What this guide will do is walk you through the migration end-to-end, with particular attention to the conceptual translation layer that every other guide skips.

Here’s what trips up most Jira-to-Linear migrations: the teams run the Jira importer, get their data into Linear, and then try to recreate their Jira structure in Linear. Jira had projects with epics and sprints. So they look for “Projects” in Linear, create one per Jira project, and try to set up sprints. Then they discover that Linear “Projects” aren’t the same as Jira “Projects,” that “Cycles” aren’t quite the same as “Sprints,” and that their whole structure doesn’t quite work.

The solution is to understand the conceptual differences before you start the import — not after.

---

Before You Migrate — Understand the Conceptual Differences

This is the most important section in this guide. Linear and Jira organize work around fundamentally different concepts. The mapping is counterintuitive in at least one critical place.

Jira concept	Linear equivalent	Translation notes
Project	Team	Linear Teams map to functional groups (Engineering, Design, Product) — not bounded work initiatives
Epic	Project	Linear Projects are the bounded work initiative (a feature, a release, a quarter’s goals)
Sprint	Cycle	Linear Cycles are time-boxed — optional; many teams don’t use them
Story / Task	Issue	Direct mapping
Sub-task	Sub-issue	Direct mapping
Component	Label or Team	No perfect equivalent; use Labels for cross-cutting concerns
Board (Scrum/Kanban)	View (Board or My Issues)	Linear’s board view is per-status, not per-sprint
Workflow / Status schema	Status + Workflow	Linear has opinionated defaults; custom statuses available
Priority (P1–P5)	Priority (Urgent/High/Medium/Low/No priority)	Mostly direct; adjust numbering to labels
Story points	Estimates	Same concept, different UI
Versions / Fix version	Milestones	Broader concept in Linear

The critical counterintuitive mapping: Jira “Projects” → Linear “Teams.”

In Jira, a “Project” is typically a top-level container for a team’s work: the Engineering project, the Design project, the Mobile project. In Linear, this concept is called a “Team” — it represents the functional group that does the work.

Linear “Projects” mean something different: they are bounded work initiatives with a defined scope and end date. A Linear Project is more like a Jira Epic or a major Jira version — it’s “Q2 Mobile Launch” or “Authentication Refactor,” not “Mobile Team.”

If you create Linear Projects to mirror your Jira Projects, you end up with a structure that doesn’t fit how Linear works — and you’ll be fighting the tool instead of benefiting from it.

The goal of migrating to Linear is not to have Jira with a better UI. It’s to simplify your workflow. Linear works best when you adopt its organizing philosophy rather than recreating Jira’s structure in a different skin. Resist the urge to recreate every Jira workflow in Linear — some of that complexity exists because Jira required it, not because your team actually needs it.

---

Pre-Migration Checklist

Do this before touching the Linear importer:

• Audit your Jira projects. Which are still active? Archive or close stale projects before migrating — don’t import 3-year-old issues nobody will reference.
• Map your Jira projects to Linear Teams using the concept table above. Write out the mapping explicitly: “Jira: Engineering → Linear: Engineering Team.”
• Map your Jira Epics to Linear Projects. These become the bounded work initiatives in your new workspace.
• Identify custom fields that matter. Not all custom Jira fields survive the migration. Decide which to preserve as Linear Labels or custom fields, and which to drop.
• Document your current Jira workflow statuses. Choose whether to use Linear’s default statuses (Backlog, Todo, In Progress, In Review, Done, Cancelled) or create custom ones. Default is recommended — custom statuses add complexity without much benefit for most teams.
• Decide who gets access to Linear on day one. Set up team members before the import so issues can be assigned correctly.
• Set a migration date and communicate it. Run both tools in parallel for one to two weeks maximum. Longer parallel running creates split context — the team loses track of which tool is the source of truth.

---

Step 1 — Set Up Your Linear Workspace

[AFFILIATE_LINK_PENDING: linear]

Create your Linear workspace at linear.app. The key setup decisions before importing:

Teams structure. This is the most important setup decision. Create Linear Teams that correspond to your Jira Projects (Engineering, Design, Product, Mobile — whatever your functional groups are). Do this before importing. If you import first and create Teams later, you’ll need to manually reassign issues.

Linear’s free plan supports up to 250 issues. If you’re migrating a large Jira backlog, start a Linear Plus plan ($8/user/month) before the import to avoid hitting the limit mid-migration.

Invite your team. Add team members to Linear and assign them to the correct Teams. The importer will map Jira assignees to Linear members by email address — make sure everyone who has issues assigned to them in Jira has a Linear account before you import.

---

Step 2 — Map Your Jira Projects to Linear Teams

Before running the importer, finalize your mapping. Here’s a practical example for a typical engineering team:

Jira structure	Linear structure
Jira Project: Engineering	Linear Team: Engineering
Jira Project: Design	Linear Team: Design
Jira Project: Mobile	Linear Team: Mobile
Jira Epic: Q2 Mobile Launch	Linear Project: Q2 Mobile Launch (under Mobile Team)
Jira Epic: Auth Refactor	Linear Project: Auth Refactor (under Engineering Team)
Jira Component: Backend	Linear Label: Backend
Jira Component: Frontend	Linear Label: Frontend
Jira Story: MOBILE-234	Linear Issue (under Mobile Team)
Jira Sub-task of MOBILE-234	Linear Sub-issue (child of Linear Issue)

The cleaner your Jira structure, the cleaner your Linear import. If your Jira has evolved over years into an inconsistent mix of project structures, this mapping step is where you decide what to keep and what to simplify.

---

Step 3 — Import Your Jira Issues with Linear’s Official Importer

In Linear: Settings (gear icon) → Import → Jira.

The importer will ask you to authenticate with Jira via OAuth or an API key. After authentication:

1. Select which Jira projects to import. Don’t import everything — only active projects.
2. Map Jira statuses to Linear statuses. You’ll see your Jira statuses on the left and Linear’s statuses on the right. Map “To Do” → “Todo”, “In Progress” → “In Progress”, “Done” → “Done”, etc. Custom Jira statuses map to the closest Linear equivalent.
3. Map Jira priorities to Linear priorities. P1/Highest → Urgent; P2/High → High; P3/Medium → Medium; P4/Low → Low; P5/Lowest → No priority.
4. Review and confirm. The importer shows a preview count before executing.

What imports cleanly: Issue titles, descriptions (including formatting), status, priority, assignee, comments, and file attachments.

What doesn’t import cleanly:

• Jira custom field values — some transfer as metadata, others are dropped. Decide during your checklist phase which custom fields to preserve.
• Jira Sprint assignments — the importer doesn’t assign imported issues to Linear Cycles. You’ll do this manually post-import.
• Jira link types — linked issues (blocks, is blocked by, relates to, duplicates) become generic relations in Linear. You’ll lose the specific link type labels.
• Jira time logs — time tracking history does not migrate.

Import time varies: a 1,000-issue Jira project typically imports in 5–10 minutes.

---

Step 4 — Assign Issues to Cycles (Optional) and Clean Up

After the import completes:

Assign to the current Cycle (if your team uses Cycles/sprints). Issues that were in your active Jira Sprint should move to your current or next Linear Cycle. In Linear, open your Team’s Cycle view and drag or bulk-select the relevant issues.

Review status mapping. Some Jira statuses may have mapped generically — check for issues that landed in “In Progress” when they should be “In Review” or “Todo.” Bulk-update by filtering by status and selecting all.

Clean up priority distribution. Large Jira backlogs often have unrealistic priority assignments — everything set to P1 or P2. This is a good moment to reset priority to reflect actual current importance, not historical urgency from 18 months ago.

Archive or cancel stale issues. Issues marked Done or Won’t Fix in Jira should be cancelled or left in Done status in Linear — not left in the active backlog. Linear’s backlog works best when it only contains issues that might actually be worked on.

Create Linear Projects from Jira Epics. For each active Jira Epic that mapped to a Linear Project (see Step 2), create the Linear Project and link the relevant imported issues to it.

---

Step 5 — Recreate Workflows and Notifications

Linear Workflow automations. Linear’s workflow rules handle common automation needs: auto-assign issues to a specific member when they move to “In Progress,” auto-close issues when a PR is merged, or notify a team when a high-priority issue is created. Map the Jira automation rules your team actually uses — not all of them, just the ones people notice when they don’t work.

Slack integration. Configure Linear’s Slack integration to replace Jira’s Slack notifications. In Linear: Settings → Integrations → Slack. Set up notifications for issue assignments, status changes, and mentions in comments. Linear’s Slack integration is cleaner than Jira’s — it surfaces the right information without the noise.

GitHub integration. If your team uses GitHub, the Linear–GitHub integration is one of the best reasons to make this move. In Linear: Settings → Integrations → GitHub. Link your repositories. Once connected, opening a PR with a Linear issue ID in the branch name or commit message automatically links the PR to the issue and moves the issue to “In Review” when the PR opens, and to “Done” when it merges.

Saved Views. Replace your Jira saved filters (JQL queries) with Linear Views. Common filters to recreate: “My active issues,” “High priority in-progress this week,” “Unassigned backlog,” “Issues in current Cycle.” Views in Linear use a UI filter builder rather than JQL — less powerful for complex multi-condition queries, but sufficient for everything most teams actually use.

---

The Mindset Shift — What Linear Is Not

Honest assessment: Linear is not the right tool for every team, and some Jira features genuinely don’t have Linear equivalents.

JQL. Jira’s query language is powerful for large-scale filtering across thousands of issues with complex conditions. Linear’s View filters cover common cases but can’t replicate arbitrary JQL for power users who rely on it.

Custom workflow schemas. Jira lets each project have a completely different set of statuses and transitions. Linear has opinionated defaults and limited custom status support. This is by design — it prevents workflow fragmentation — but if your Jira has 12 different custom workflows across 12 projects, you’re giving something up.

Plugin marketplace. Jira’s 3,000+ marketplace apps cover everything from time tracking to compliance reporting to custom integrations. Linear’s integration surface is growing but much smaller.

Enterprise compliance. Linear is gaining enterprise features (SSO, SAML, audit logs), but Jira’s enterprise compliance posture is more mature for large organizations with strict procurement requirements.

For most engineering teams under 150 people, none of these are blocking limitations. For enterprise teams with highly customized Jira configurations, weigh the migration cost honestly before committing.

For a broader look at where Linear fits among developer tools, see our developer tools roundup.

---

FAQ

Does Linear have a Jira importer? Yes. Settings → Import → Jira. Handles issues, status, priority, assignees, comments, and attachments. Custom fields and sprint assignments require manual cleanup post-import.

Can I migrate Jira epics to Linear? Yes — as Linear Projects (not Linear Epics, which don’t exist). See the concept mapping table in Step 0.

Does Linear support sprints? Yes, called Cycles. They’re optional — many teams run without them on a continuous backlog model.

What is the equivalent of Jira’s JQL in Linear? Saved Views. Less powerful for complex queries, but covers common filter use cases via a UI filter builder.

Is Linear free? Free for up to 250 issues. For active teams migrating from Jira, the Plus plan ($8/user/month) is required to remove the issue limit.