Importer

Learn best practices for importing to Linear. Select the tool you're importing from in the table of contents for specific instructions.

Linear Concepts

A Linear workspace is our top level concept, which contains one or many teams. We recommend that each company using Linear uses only one workspace.

Issues and projects are the core entities used to manage work in Linear. Each issue belongs to a single team, while projects can belong to one or many teams. Other concepts in Linear can be scoped to a team or a workspace like Views (filter based groups of issues or projects), Initiatives (hand-picked groups of projects) and more.

When you import from another service to Linear, we'll attempt to match data from the source tool with the closest concept in Linear. If a concept from the source tool does not translate well to Linear, it may not be imported; please see details on your individual service for further details.

Pre-import best practices

Imports run most smoothly when you prepare for them well. Consider the below before starting your first import.

Which data is worth importing?

If there is data that is no longer relevant to your organization's day to day work, consider whether it needs to be in Linear at all (perhaps a CSV of exported data from long-resolved issues is sufficient). Some organizations choose to use Linear as a "clean break" from their legacy tool and import only where absolutely necessary. Others prefer to maintain as full a historical record as possible in one place.

If you're importing when evaluating Linear instead of transitioning all at once, you may wish to run a pilot by importing just a few teams.

Choose an import method

We offer two main methods of importing to Linear; our dedicated migration assistants in-product, as well as a CLI import tool. We recommend using our dedicated migration assistants whenever possible as they retain much more data from the original source, are easier to use, and if need be imports completed with this process can be deleted entirely.

Use the CLI importer when importing from a service that we don't have a dedicated migration assistant for. Migration assistants are available for Jira, GitHub Issues, Asana, Shortcut and Linear. More information about the CLI importer can be found here.

Understand the import process

You'll first need to have an Admin role in Linear in order to access our import tools. You may also need high permissions in the tool you're importing from in order to access the data. In general, the migration assistants follow this path:

Step	Detail
Setup	Provide an access token, or sign in to your source tool from Linear.
Review	We'll display the issues, projects, labels, users and other data fetched from the information provided.
Choose what to import	Choose whether to import only open issues, or also to import closed and stale issues to the archive. The archive can be accessed through the overflow menu on each team in your sidebar.
Map users	For each user fetched, choose not to import them, to create a new user from an email address, or to map them to an existing user in your Linear workspace.
Confirm	At this point, all data available to import will be summarized. If it looks as you expect, hit Finish to start the import.

How to import

Find instructions on importing from your source tool below:

Jira

Find instructions here

GitHub Issues

Find instructions here

Asana

Navigate to Settings > Workspace > Import/Export. You must be an admin in Linear to access this page.
Click on the button for Asana
Enter your Asana personal access token. You can obtain your personal access token by navigating to your Asana developer console.
Enter your Asana team name
Select which Linear team to import issues into
Click Next to start importing

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

Asana	Linear
Priority	Priority
Notes	Issue description (converted to Markdown)
Attached files	Added to description, all files except images are converted to links
Tags	Labels (team-level)
Assignee	Assignee
Projects	Projects
Comments	Comments

An issue 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.

Shortcut

Navigate to Settings > Workspace > Import/Export. You must be an admin in Linear to access this page.
Click on the button for Shortcut
Enter your Shortcut personal access token. You can obtain your personal access token by navigating to your Asana developer console.
Enter your Shortcut team name
Select which Linear team to import issues into
Click Next to start importing

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

Shortcut	Linear
Name	Title
Description	Issue description
Tasks	Appended to the description
External tickets	Appended to the description
State	Mapped to the most similar Linear status
Story type	Added as label (team-level)
Tags	Added as label (team-level)
Owners	First owner added as assignee when possible
Epic	Created as projects
Comments	Comments
Estimate	Estimate
Due date	Due date
Priority	Priority

Trello, Pivotal Tracker, or Clickup

To import issues from Trello, Pivotal Tracker or Clickup, use our open source CLI importer.

While this import type can also be used to customize imports that have a migration assistant, we don't recommend this as the CLI importer will not import data supported by the migration assistant like comments, projects or cycles.

Our Command Line interface (CLI) tool uses CSV exports from the source tool and requires some technical expertise. Access it at the link or from Settings > Workspace > Import/Export. For those unfamiliar with the command line, this video may help with getting started with a CLI import.

Linear

To move data from one Linear workspace to another, please contact support@linear.app so we can facilitate the transition for you. Include the URLs of the workspaces you wish to import, and which workspace you'd like to keep using moving forward.

Please note that permissions for this task require you to be an admin in both the source and destination workspace, and for your accounts in each workspace to use the same email address.

At this time, we are not able to import issues for you from a provided CSV -- the import is team by team only.

Linear (old)	Linear (new)
Title	Title
Description	Description
Estimate	Estimate
Labels	Labels
Due date	Due date
Comments	Comments
Workflow state	Workflow state
Project	Project
Relationships	Relationships
Sub-issues	Sub-issues

Other

If you'd like to import from a tool not listed here, you can still do so using our CLI importer and the CSV file of your exported data.

First, you'll want to generate a Linear export file from Settings > Import/Export > Export CSV. Remove any exported text but leave the headers of each column.

In the fields below, paste data from your source tool's export file, and save the CSV.

Title - Issue title
Description - Issue description
Priority - Issue priority
Status - Issue state (workflow)
Assignee - Issue assignee (user's full name)
Labels - Added as a label

Once the above data is in the attached format, you can import the CSV using the CLI and selecting the "Linear" csv option when prompted.

For those unfamiliar with the command line, this video may help with getting started with a CLI import.

Troubleshooting

If something did not import as you expected, please check the section for your specific service to confirm whether we support importing that property. If it looks like something didn't import properly, let us know at support@linear.app.

If you need to delete an import in order to re-import once more, you can do so through Import/Export settings, on the overflow menu on a specific import. If no overflow menu appears, please contact Linear support for assistance deleting it.

Reimporting from the same external source to the same Linear team without deleting the initial import first will skip any already-imported issues.

Invite & Manage Members

Teams