How to migrate from Jira to Linear: a step-by-step guide

Switching from Jira to Linear is usually a quick decision. Moving years of issues, comments and files is not. This guide walks through a migration plan that works for teams of five and for teams of five hundred: what to decide up front, what to clean up, which import method fits, and how to switch over without a week of "where did that ticket go?".

1. Decide what a finished migration looks like

Write down, before touching any tool, what has to be true on the day you switch:

• Scope. Which Jira projects move, and how far back? All history, or only issues updated in the last year?
• What must survive. Issue keys, comments, attachments, pull request links, sprints, fix versions, watchers. Rank them — they decide which import method you can use.
• Owner and date. One person owns the migration end to end. Pick a cut-over date and work backwards from it.
• How long Jira stays around. Read-only for 30 days? 90? Forever as an archive? This decides how much you can afford to leave behind.

Teams that skip this step usually discover on cut-over day that "we'll keep Jira for reference" means paying for both tools for a year.

2. Take inventory of your Jira site

You can't plan a move without knowing what's in the boxes. Collect, per project:

A JQL search such as project = ENG gives you issue counts per project. Your Jira admin can tell you total attachment storage.

3. Clean up before you move

Everything you import, you'll have to live with in Linear. A few hours of cleanup pays for itself:

• Close or archive stale work. Issues nobody has touched in two years rarely need to be open in Linear. Import them as completed or canceled, or leave them out.
• Merge duplicate labels and components. frontend, Frontend and FE should become one label before the import, not after.
• Decide on every custom field. For each one, choose: turn it into a label, append it to the description, or drop it.
• Simplify statuses. Seven Jira statuses that mean "in progress" should become one or two Linear workflow states.

4. Map Jira concepts to Linear

Linear is deliberately simpler than Jira, so some concepts merge and a few disappear. The short version:

The Jira to Linear mapping guide covers every field, including statuses, priorities and custom fields.

5. Choose an import method

There are five realistic ways to get your data across:

1. Linear's built-in Jira importer. Free and fast for the basics: titles, descriptions, statuses, comments and images. It runs once, and it leaves fix versions, sprints, pull request links, watchers, custom fields and most non-image files behind. See what Linear's Jira importer leaves behind.
2. CSV export and import. Works for small, simple projects. You lose comments' structure, attachments and links, and CSV imports can't be kept in sync.
3. Linear's Jira Sync integration. Keeps new issues flowing between the two tools. It's a bridge for teams running both, not a way to move history.
4. A dedicated migration tool such as Jira-to-Linear-importer, which imports everything above, keeps issue keys and can sync incrementally until you switch.
5. Your own scripts. Possible, and more work than it looks: rich-text conversion, attachment uploads, rate limits, user matching and restarts each take a day or more.

Pick the cheapest method that keeps everything on the "must survive" list from step 1.

6. Back up Jira

Whatever method you choose, take a full backup of your Jira site before the first import, including attachments. Jira Cloud's backup manager can create one. Store it somewhere that will outlive your Jira subscription — it's your archive once Jira is gone.

7. Run a test import

Import into a test team (or a separate test workspace) first, then check a sample of 20 issues by hand:

• Are descriptions readable, with headings, code blocks, tables and mentions intact?
• Do attachments open — from Linear, not from a link back to Jira?
• Are statuses, assignees, priorities and estimates right?
• Do parent issues, sub-issues and relations point to the right places?
• Do comments keep their order and authors?

Fix the mapping and run it again. Two or three rounds are normal.

8. Plan the cut-over

There are two common strategies:

• Freeze and move. Make Jira read-only on a Friday, import over the weekend, start Monday in Linear. Simple, but it needs a quiet weekend and a single big import that must work the first time.
• Import early, then sync. Import everything a week or two ahead, keep syncing changes while the team works in Jira, then switch on a normal workday. Less risk, but it needs a tool that supports incremental sync.

Either way, cut over between sprints so nobody has to move work mid-sprint.

9. Switch over

On the day itself: freeze Jira, run the final import or sync, spot-check, and announce the switch with links to the new teams. The migration checklist has every step.

10. After the move

• Point GitHub or GitLab, Slack and any automation at Linear, and turn off Jira webhooks and automation rules.
• Update links in docs and wikis. If your issue keys are unchanged, a single search-and-replace of the Jira URL prefix fixes them — see keeping your Jira issue keys.
• Keep Jira read-only for a few weeks, then export the final backup and cancel.
• Collect feedback after two weeks. Most teams adjust labels and workflow states once they've lived in Linear for a sprint or two.