How to Migrate From Jira to Linear - A Developer's Guide

Jira is everywhere in engineering. It's also heavy. Linear is built for developers who want something lighter and faster.

If you're considering moving from Jira to Linear, the good news is the importer works. The challenge is handling everything the importer misses.

This guide covers what the Linear importer does well and what you'll need to handle manually. Understanding those gaps makes the difference between a smooth migration and a frustrating one.

Why Teams Leave Jira for Linear

Jira is powerful. It's also slow.

Developers spend time clicking through menus instead of working. Linear is built on the opposite principle: speed.

Linear has keyboard shortcuts for everything. Issues sync with GitHub automatically.

The interface doesn't distract. For engineering teams that spend their days in code, Linear feels native in a way Jira doesn't.

But the move isn't trivial. Jira's complexity sometimes holds important context. Linear's simplicity requires discipline to maintain that context.

Step 1 - Understand Linear's Jira Importer

Log into Linear and go to Settings > Integrations > Jira. Connect your Jira account using OAuth. Linear will scan your Jira instance and show you what it can import.

The importer handles: issues, comments, labels, assignees, due dates, and priority. It does NOT import custom fields, workflows, screens, or issue links.

This asymmetry matters. If you've used custom fields to track things Jira wouldn't normally track, you'll need to redesign that in Linear.

Step 2 - Audit Your Jira Instance

Before importing anything, export your Jira data as backup. Go to Jira Settings > System > Backup and create a backup. Download it and store it safely.

Then audit your Jira structure. Answer these questions:

How many projects are you importing?
How many custom fields are you using?
What issue types matter? (Story, Bug, Task, Epic, etc.)
How many issue links do you have? (blocks, relates to, etc.)
What workflows have you customized?

This audit tells you how much manual work you'll face after import.

Step 3 - Plan Your Linear Project Structure

Jira projects map to Linear projects. But the context is different.

Jira projects often correspond to products or components. Linear projects often correspond to teams or initiatives.

Think about how your teams actually work. If you have a "Backend" team and a "Frontend" team, you might have one Linear project per team. If you organize by product, you might have one Linear project per product.

Don't just replicate your Jira structure. This is your chance to reorganize based on how teams actually work, not based on legacy Jira setup.

Step 4 - Recreate Custom Fields as Linear Context

Jira custom fields store metadata. Linear doesn't have custom fields, but you can achieve similar results using Labels, Status, and Estimates.

If Jira had a custom field called "Customer Impact" with values like "High," "Medium," "Low," create a Label set in Linear called "Impact" and use those same values.

If you had a "Sprint" custom field, use Linear's native cycle feature instead. This gives you time-based grouping without custom fields.

The goal is translating custom field context into Linear's simpler model. Sometimes this requires rethinking how you track information.

Step 5 - Handle Issue Relationships Differently

Jira issue links are powerful. Story A blocks Story B.

Epic C relates to Story D. Linear handles some of this natively (cycles, teams) but not all of it.

For critical relationships that Jira tracked with issue links, use Linear's "relates to" feature or document them in issue descriptions. Complex dependency systems (which happens rarely) might stay in Jira for reference.

If you have real dependencies (Story A blocks Story B in the literal sense), you can document them in descriptions. For softer relationships, let them go.

Step 6 - Import Your Data

Once you've done the planning, run the Linear Jira importer. It will import all issues from the selected Jira projects into new Linear projects.

The import creates one Linear project per Jira project. Issues come with their comments, descriptions, and assignees. Status maps to Linear status.

Priority maps to priority. Dates come through.

The import is usually fast - even large instances import in minutes. After import, you get a report of what succeeded and what didn't.

Step 7 - Verify the Import

After import, spend time checking that data came through correctly. Open a few issues and verify:

Descriptions are complete
Assignees are correct
Comments are there
Due dates came through
Priority is set

If custom fields contained critical information, search for that context in issue descriptions. You'll need to recreate how you reference it.

Step 8 - Integrate With GitHub

Linear's GitHub integration is why many engineering teams switch. Issues sync with pull requests. A PR linked to a Linear issue automatically updates that issue's status.

Go to Settings > Integrations > GitHub and connect your GitHub repositories. For each repository, choose which Linear project it maps to.

Once integrated, you can reference Linear issues in commit messages. "Fixes LIN-123" in a commit message automatically closes that issue when the PR merges.

Step 9 - Recreate Workflows

Jira workflows define issue lifecycle: Open > In Progress > In Review > Done. Linear has simpler workflows by design, but you can customize them.

Go to Project Settings > Workflows and review Linear's default statuses. Linear usually has: Backlog, Todo, In Progress, In Review, Done. These usually work as-is.

If you had custom workflow states in Jira, decide which ones matter. If you had "In QA," you might use "In Review." If you had "Documentation," you might just use "Todo."

Custom workflow states rarely improve outcomes. Don't recreate complexity. Use Linear's defaults unless you have specific reasons not to.

Step 10 - Train Your Team

Linear's interface is intuitive, but it's different from Jira. Developers familiar with Jira need 2-3 days to be fully comfortable.

Key things to train on:

Keyboard shortcuts (Cmd+K to search, J to jump to issue, etc.)
GitHub integration (how PR linking works)
Cycles (equivalent to sprints)
Filters (how to find your issues quickly)

Most developers learn by doing. Create some test issues together.

Show how to link them to GitHub. Then let people work.

Step 11 - Maintain a Jira Archive

Keep your Jira instance running in read-only mode for 30 days. This gives you a safety net if you need to reference old structure or lost data.

After 30 days, you can confidently archive it. Export the backup. Then disable Jira or take it offline.

Common Migration Challenges

Custom field loss. Jira's custom fields don't import. If they held critical information, you'll need to find another way to capture that.

Workflow complexity loss. Linear's workflows are simpler than Jira's. Some teams find this limiting initially, then discover that simpler workflows work better.

Notification overload. Linear's notifications are noisier than Jira's initially. Take time to tune notification settings so your team doesn't get overwhelmed.

Version and release tracking. Jira releases are sophisticated. Linear's cycles are simpler. You might lose some release-tracking capability - decide if that matters.

Frequently Asked Questions

Should I import all Jira projects at once? No. Start with one. Run it in Linear for a week. Make sure the workflow works, then import others. This prevents large-scale problems.

Can I keep Jira running alongside Linear? Yes, but your team needs to know which is the source of truth. Otherwise you'll spend time updating both systems. Use Jira as read-only and Linear as active.

What about my Jira automation rules? Linear has automations, but they're different. Common Jira automations (like "move to done when PR merges") are built into Linear's GitHub integration. You might not need explicit automation rules.

Do I need to keep any custom fields? Rarely. Think about whether you'd use the information. If you're not looking at it now, you won't look at it in Linear. Cut it.

Can tools like Huddle help with the transition? If you're juggling Linear and other PM tools, Huddle aggregates tasks across systems into one dashboard. This can ease the transition if you're not fully off Jira yet.

How long does the whole process take? For a small instance (under 500 issues), plan one week. For larger instances, plan two weeks. Most of that time is planning and verification, not the actual migration.

Linear's simplicity is both its strength and the reason migration requires care. You're not just moving data - you're embracing a different philosophy of how development work is tracked.

Take time to understand that philosophy. Your team will be faster on the other side.