Importer
Learn best practices for importing to Linear. Select the tool you're importing from in the table of contents for specific instructions.
![Image of migration assistants](https://cdn.sanity.io/images/ornj730p/production/d2f61b4eeb982988a066a5416eaa81bb547178b3-2880x1769.png?w=1440&q=95&auto=format&dpr=2)
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.
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 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.
- Navigate to Settings > Workspace > Import/Export. You must be an admin in Linear to access this page.
- Click on the "Linear to Linear migration" 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 migration".
- Custom views / view preferences / views attached to projects or initiatives
- Favorites / reminders / drafts / inbox notifications
- Integrations / webhooks / OAuth clients / API keys
- 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.
In the fields below, paste data from your source tool's export file, and save the CSV.
Title
- Issue titleDescription
- Issue descriptionPriority
- Issue priorityStatus
- 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.