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. We also have a resource for switching tools in our switch instruction manual.

Choose an import method⁠

We offer two main methods of importing to Linear; our dedicated import assistants in-product, as well as a CLI import tool. We recommend using our dedicated import 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 import assistant for. Import 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 import 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.

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.

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 and videos are converted to links
Tags	Labels (team-level)
Assignee	Assignee
Projects	Projects
Comments	Comments (markdown respected)
Status	Imported status will be Backlog or Done only

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.
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 or Pivotal Tracker⁠

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

For Trello, please note that imports must be run from individual board exports, not from the overall workspace.

While CLI imports can also be used to customize imports for services with an import assistant, we don't recommend this as the CLI importer will not import data supported by the import assistant like comments or projects.

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 import data from one Linear workspace to another, first ensure that you have an admin account in both workspaces using the same email login credential.

If there isn't already an admin using the same email credential in both source and destination workspaces, invite an admin from the destination workspace to the source workspace (or vice versa) and have them run the import. For best results, avoid creating multiple accounts on the same workspace under different emails.

Navigate to Settings > Workspace > Import/Export. You must be an admin in Linear to access this page.
Click on the "Linear to Linear import" button.
Select the workspace you would like to import. We will only show workspaces under the same email address where you are an admin member.
Select the teams you would like to import from this workspace.
Choose how to map members from the workspace you are importing from to your current workspace.
Review a summary of the import.
Click "Start import".

This import will not carry over all data associated with your source workspace. Please note that the data below will not transfer.

Custom views / view preferences / views attached to projects or initiatives
Favorites / reminders / drafts / inbox notifications
Integrations* / webhooks / OAuth clients / API keys (Integrations will need to be installed on the new workspace and will not resume notifications or automations for imported issues in most cases.)
Billing/plans* (please contact support@linear.app for assistance with billing transfers)
Workspace URL (you can switch this manually after import)
Personal and Workspace settings
Roles (current admins will be imported as members, you will initially be the only admin. Guests will carry over with the same permissions.

Linear (old)	Linear (new)
Title	Title
Description	Description
Estimate	Estimate
Labels	Labels
Due date	Due date
Comments	Comments
Workflow state	Workflow state
Sub-issues	Sub-issues
Relationships	Relationships
Projects	Projects
Initiatives	Initiatives
Team templates	Team templates

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. This will give a CSV in the format that the CLI importer expects for a Linear import.

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 (separate by commas for multiple labels)

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.

Audit log

Exporting Data