Importer
Import data from other tools into Linear.
Overview
We have two tools for importing data to Linear. 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.
Service | Issue Migration Assistant | CLI Importer |
---|---|---|
Jira | ✓ | ✓ |
Asana | ✓ | ✓ |
GitHub Issues | ✓ | ✓ |
Shortcut (Clubhouse) | ✓ | ✓ |
Pivotal Tracker | ✓ | |
Trello | ✓ | |
Linear > Linear | Contact Support | ✓ |
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
Issue Migration Assistant
The issue migration assistant guides you through the process of importing issues to Linear from Asana, Jira, Shortcut or GitHub. It connect to your other issue tracker via their API to import issues. 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.
Go to Settings > Workspace > Import/Export to import issues using our issue migration assistant.
Asana
- Navigate to Settings > Workspace > Import/Export.
- 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 |
Issues cannot belong to multiple projects in Linear, so one project will be chosen if issues are assigned to multiple Asana projects.
GitHub Issues
If you want GitHub issues to be synced in advance of this import, we recommend setting that up first. Details can be found here.
- Navigate to Settings > Workspace > Import/Export.
- Click on the button for GitHub
- OAuth into GitHub from the importer page
- Select the repo where your current Github issues live
- Select the team you want to import them into on Linear.
By default, we will import any projects associated with the repos you choose. You will also have the option to choose to import all projects from the organization level.
We'll map fields in GitHub Issues to these fields in Linear:
GitHub Issues | Linear |
---|---|
Title | Title |
Description | Description |
Labels | Labels (team-level) |
Projects | Projects |
Comments | Comments |
Jira
The Jira importer will work with self-hosted Jira servers as long as the self-hosted install is also accessible publicly on the web.
- Navigate to Settings > Workspace > Import/Export.
- Click on the button for Jira.
- There are two options for Jira imports:
- uploading a CSV, or
- providing your API credentials.
Import via CSV
- Export a CSV from Jira by searching for your project under advanced issue search in JQL (project=TEST, for instance).
- Export the data as a CSV and choose the "all fields" option.
- Attach this file in Linear where prompted and optionally add data in the other requested fields.
Import via API
If importing over API credentials, you'll also need to be an admin in Jira of the project you're importing.
- Enter your personal access token (obtained from your Atlassian settings).
- Enter your project key
- Enter your email address you use for your Jira account.
- Enter your installation or cloud hostname. Remember to remove the
http://
and anything following.net
. - Select the team you want the import to go to
- Click Next
You will be guided through configuration options during the import process. You will have the option to:
- import into an existing team or a newly created team on your workspace.
- map each Jira user to an existing Linear user, invite Jira users to your Linear workspace, or take no action for certain Jira users.
- The CSV file must only contain issues form a single Jira project (otherwise, keys could contain conflicting numbers).
- You must check the boxes to import all the closed/done/archived issues as well. Otherwise, we will only import the active issues and the number scheme will start at whatever the highest was from the import.
We'll map fields in Jira to these fields in Linear:
Jira | Linear |
---|---|
Summary | Title |
Description | Converted into markdown and used as issue description |
Priority | Priority |
Issue Key | Used in backlink |
Issue type | Mapped to the most similar Linear status |
Type | Added as label (team-level) |
Release | Added as label (team-level) |
Epic | Added as project (or optionally as label) |
Comments | Comments |
Estimate | Estimate |
Due date | Due date |
Parent/Child | Parent/sub-issue |
Label | Label |
Status | Status (best effort conversion) |
Import and sync with Jira
If your team is moving to Linear but your broader organization is still using Jira, it can be advantageous to have your team's work in Linear accurately reflected back to your broader org's Jira instance.
To import issues from Jira as synced, configure Jira links in Settings > Integrations > Jira for each of the Jira projects you're importing into Linear prior to running those imports. If you've already imported from that project and wish to re-import it as synced, delete the import from Settings > Import/Export, configure the sync and re-import.
This sync feature will keep most issue properties aligned between the original issue in Jira, and the imported issue in Linear. Optionally, choose to enable bi-directional sync so that issues created in Linear will also sync to Jira (otherwise, only issues created in Jira will sync to Linear.)
For best performance in syncing fields like assignee and creator, individual Linear users should also connect their personal Jira accounts to Linear in integration settings prior to import as well.
Running an import from a synced Jira project will import those issues as synced automatically.
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:
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 or labels |
Comments | Comments |
Estimate | Estimate |
Due date | Due date |
Priority | Priority |
Linear > 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.
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 |
CLI Importer
To import issues from other services, such as Trello, Pivotal Tracker and 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 format and requires some technical expertise. Access it at the link or from Settings > Workspace > Import/Export.
Trello
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:
Trello | Linear |
---|---|
Name | Title |
Description | Trello markdown formatted description |
URL | URL of Trello card |
Labels | Added as a label (team-level) |
Attachments | Added 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
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 Tracker | Linear |
---|---|
Title | Title |
Description | Description (converted to Markdown) |
Labels | Added as a label (team-level) |
Owned By | Assignee |
URL | URL of Pivotal Tracker story |
Created at | Preserves 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.
Clickup
Clickup Spaces can be imported into a Linear team from the CSV file exported from Clickup.
As Clickup is not a service explicitly handled in the CLI importer, the best way to import is by moving the exported data into a Linear-style CSV that can be imported by choosing the Linear option above.
Import Mapping
In general, we map basic features to their Linear equivalent.
- Labels will be imported as team-level labels.
- Embedded images 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.
Import History
If someone on your team imported issues in the past, you'll see a history of past imports on the settings page.
Delete an import
The best way is to delete the import from the Previous Imports section in the Migration Assistant settings page. You can do this within 7 days of the original import. This allows for you to import test data or redo the import with different settings. Imports made using our CLI importer will not appear here. Migrated issues imported through the assistant will also have a Migrated label for easy filtering.
If 7 days have passed or you have used our CLI importer, you can delete the imported team or move the imported issues to a new team and then delete that team.