Jira to Linear migration checklist

A Jira to Linear migration is a project like any other: it goes smoothly when someone owns it and works through a list. Copy this checklist into a Linear issue (or a doc) and tick things off. For the reasoning behind each step, see the step-by-step migration guide.

Four weeks before

• Name one owner for the migration
• Pick a cut-over date at a sprint boundary
• List the Jira projects that move, and how much history each keeps
• Rank what must survive: issue keys, comments, attachments, PR links, sprints, versions, watchers
• Record issue counts and attachment storage per project
• List custom fields in use and decide label, description or drop for each
• List integrations: GitHub, GitLab or Bitbucket, Slack, Confluence, automation rules, webhooks
• Choose an import method that keeps everything on the must-survive list
• Decide how long Jira stays available read-only after the switch
• Tell the team the date and what will change

Two weeks before

• Clean up: close stale issues, merge duplicate labels and components
• Map Jira statuses onto Linear workflow states (mapping guide)
• Create the Linear workspace and invite everyone with the same email address they use in Jira
• Create one team per Jira project, using the same key — and don't create issues in it yet
• Set up workflow states, labels, priorities and the estimate scale for each team
• Take a full Jira backup, including attachments, and store it outside Jira
• Run a test import into a test team or workspace
• Check 20 issues by hand: formatting, mentions, attachments, relations, statuses, comments

One week before

• Fix the mapping and run the test import again
• Walk team leads through the test import
• Recreate the few views each team opens daily
• Configure cycles to start on cut-over day (sprints and cycles)
• Prepare the announcement: links to the new teams, where to ask questions
• Give the team a 15-minute Linear intro: keyboard shortcuts, cycles, triage

Cut-over day

• Close the last Jira sprint
• Make Jira read-only for everyone except admins
• Run the final import, or the final incremental sync
• Spot-check issue keys, attachments and the newest comments
• Connect GitHub or GitLab and Slack to Linear
• Turn off Jira automation rules and webhooks
• Post the announcement

After the switch

• Replace Jira URLs in docs and wikis — one search-and-replace if keys are unchanged (keeping issue keys)
• Check open pull requests link to Linear issues
• Collect feedback after two cycles and adjust labels and states
• Take a final Jira backup
• Cancel Jira when the read-only period ends

Want this done for you? Jira-to-Linear-importer handles backup, inspection, the import and incremental sync — and for large migrations, we can guide your team through the whole list.