Importer

Import issues from your existing issue tracker into Linear.

Overview

We have two tools for importing issues. A concierge-style issue migration assistant takes you through the import process from start to finish. Our command line interface importer is more rudimentary and lets you import issues by uploading a CSV. It requires some technical knowledge but is more customizable.

ServiceIssue Migration AssistantCLI Importer
Jira
Asana
GitHub Issues
Shortcut (Clubhouse)
Pivotal Tracker
Trello
Linear > Linear
Other services

G then S to go to Settings > Workspace > Import/Export

F then filter by Migrated label to find issues imported via the Issue Migration Assistant

Basics

Issue Migration Assistant

The issue migration assistant is our built-in importer that guides you through the process of importing issues to Linear from Asana, Jira, Shortcut (formerly Clubhouse) or GitHub.

It connects to your other issue trackers via the API to import issues from them. You'll need to authenticate to other services or share details with us so that we can view and transfer the issue data to Linear.

In general, we map basic features such as labels to their Linear equivalent. Attachments are imported either as an inline image in the description or a link to the file. If we can match users, we will map assignees. All imported issues include backlinks to the original issue URL in the previous issue tracker. If someone on your team imported issues in the past, you'll see a history of past imports on the settings page.

Find steps for the various importers below.

ProTip: Issues imported with the Migration Assistant will be labeled Migrated. Filter for that label, then m Cmd A to take bulk actions on those issues or remove the label completely. You can also remove the label under Team settings > Labels, which will remove it from migrated issues.

CLI importer

To import issues from other services including Trello, Pivotal Tracker, move issues from one Linear workspace to another, or to customize an import from Jira, Asana, GitHub, or Clubhouse, use our open source CLI importer.

Our Command Line Iinterface (CLI) tool uses CSV format and requires some technical expertise. Access it at the link or from Settings > Workspace > Import/Export.

Import steps

Asana

Go to Settings > Workspace > Import/Export to import issues with our issue migration assistant. You don't need technical expertise to use the importer but will need to be a Linear admin.

Enter your Asana personal access token and Asana team name, then select which Linear team to import issues into and start importing.

We'll map fields in Asana to these fields in Linear:

AsanaLinear
PriorityPriority
NotesIssue description (converted to Markdown)
Attached filesAdded to description, all files except images are converted to links
TagsLabels
AssigneeAssignee
ProjectsProjects

Issues cannot belong to multiple projects in Linear, so one project will be chosen if issues are assigned to multiple Asana projects.

We currently only support in app importing from Asana organizations. Make sure your Asana workspace is an organization before beginning an import, or convert your Asana workspace to an organization if it is not. If you do not want to convert your Asana workspace to an organization, use the CLI importer.

You cannot customize or configure additional fields when using the Issue Migration Assistant. To create a custom import, you could customize the CLI importer.

Jira

Go to Settings > Workspace > Import/Export to import issues with our issue migration assistant. You don't need technical expertise to use the importer but will need to be a Linear admin.

Enter your personal access token, project key, email address and installation or cloud hostname and then start the import. For the installation or cloud hostname, remember to remove the http:// and anything after .net.

We'll map fields in Jira to these fields in Linear:

JiraLinear
SummaryTitle
DescriptionConverted into markdown and used as issue description
PriorityPriority
Issue KeyUsed in backlink
Issue typeMapped to the most similar Linear status
Type Added as label
ReleaseAdded as label
EpicAdded as label

You cannot customize or configure additional fields when using the Issue Migration Assistant. To create a custom import, you could customize the CLI importer.

GitHub Issues

Go to Settings > Workspace > Import/Export to import issues with our issue migration assistant. You don't need technical expertise to use the importer but will need to be a Linear admin.

OAuth into GitHub from the importer page, select the repo where your current Github issues live and then which team you want to import them into on Linear.

We'll map fields in GitHub Issues to these fields in Linear:

GitHub IssuesLinear
TitleTitle
DescriptionDescription
LabelsLabels
ProjectsProjects
CommentsComments

You cannot customize or configure additional fields when using the Issue Migration Assistant. To create a custom import, you could customize the CLI importer.

Shortcut (Clubhouse)

Go to Settings > Workspace > Import/Export to import issues with our issue migration assistant. You don't need technical expertise to use the importer but will need to be a Linear admin.

Enter your Shortcut workspace access token and Shortcut team name, then select which Linear team to import issues into and start importing.

We'll map fields in Shortcut Issues to these fields in Linear:

ShortcutLinear
NameTitle
DescriptionIssue description
TasksAppended to the description
External ticketsAppended to the description
StateMapped to the most similar Linear status
Story typeAdded as label
TagsAdded as label
OwnersFirst owner added as assignee when possible
EpicAdded as label

You cannot customize or configure additional fields when using the Issue Migration Assistant. To create a custom import, you could customize the CLI importer.

Trello

Follow the instructions listed in the CLI importer. Trello boards can be imported into a Linear team from the JSON export file, which can be obtained by going into Board → Show Menu → More → Print and Export → Export as JSON.

We'll map fields in Trello to these fields in Linear:

TrelloLinear
NameTitle
DescriptionTrello markdown formatted description
URLURL of Trello card
Labels Added as a label
AttachmentsAdded as links in the description
Comments (Optional)Added in the description

While the import is limited to these fields, the importer is open source (contributions welcome) so it's possible to customize the CLI importer.

Pivotal Tracker

Follow the instructions listed in the CLI importer. Pivotal Tracker projects can be imported into a Linear team from the CSV file exported from Pivotal. It only imports chores, features, and bugs.

We'll map fields in Pivotal Tracker to these fields in Linear:

Pivotal TrackerLinear
TitleTitle
DescriptionDescription (converted to Markdown)
Labels Added as a label
Owned ByAssignee
URLURL of Pivotal Tracker story
Created atPreserves the story creation date

While the import is limited to these fields, the importer is open source (contributions welcome) so it's possible to customize the CLI importer.

Linear > Linear

The only way to move issues from one Linear workspace to another is to use the CLI importer. First, admins should export a CSV of workspace issues from the workspace you no longer want to use, then follow the instructions in the CLI importer. Archived issues will not be imported.

Archived issues will not be importer and some issue data will be lost in the transfer. If the issue data is not included in the list below, it will not be imported. One workaround is to use labels to preserve issue data (e.g. a label with Cycle 1), then upon transfer filter and update issues in bulk and remove the labels.

We'll only import the following issue data and map it to these fields in the new workspace:

Linear (old workspace)Linear (new workspace)
TitleTitle
DescriptionDescription
PriorityIssue priority
StatusStatus or best match
AssigneeAssignee
LabelsAdded as a label

While the import is limited to these fields, the importer is open source (contributions welcome) so it's possible to customize the CLI importer.

Other services

As long as you can export issues to CSV, it may be possible to use the existing CLI importer to migrate issues from services we do not currently support. You could customize the code or update a CSV export so the headers match the CSV headers for one of the already supported services.

FAQ

Did we miss something? Have a question? Email us at hello@linear.app to let us know.