Overview
The Linear importer copies one Linear team into one Shortcut Workflow. It brings over the team’s issues, projects, cycles, comments, and uploaded files, and it keeps who created, owned, and followed each issue.
Shortcut Admins run the import from Settings > Import / Sync. To bring over several Linear teams, run one import for each team.
Before you begin
Make sure that you have:
- Admin access in Shortcut.
- A Linear account that can see the team you want to import.
- The Shortcut Workflow States you want to use. Create any new Workflow States before you start, so that every Linear state has a place to go.
- Iterations turned on in Workspace Features, if you want to import Linear cycles. When Iterations are off, the importer skips cycles.
Start the import
- In Linear, open Settings > Security & access and create a personal API key.
- In Shortcut, go to Settings > Import / Sync.
- Under Auto-Import, select Linear.
- Paste the API key into API Key.
- In Team Key, type the prefix of the team’s issue IDs. For the issue
ENG-123, the Team Key isENG. - Click Next. Shortcut downloads the team’s data from Linear.
- Choose the Shortcut Workflow for the imported Stories, then click Next: Map Workflow States.
- Map each Linear workflow state to a Shortcut Workflow State, then click Next: Map Users.
- Map each Linear user, then click Next to start the import.
Shortcut emails you when the import finishes. You can delete the API key in Linear after that.
Map Workflow States
Shortcut preselects a Workflow State for each Linear state, based on the Linear state’s type. You can change any of them before you continue.
| Linear state type | Preselected Shortcut Workflow State type |
|---|---|
| Triage, Backlog | Backlog |
| Unstarted | Unstarted |
| Started | Started |
| Completed, Canceled, Duplicate | Done |
If the Workflow has no state of the matching type, Shortcut preselects its first Unstarted state.
Map users
For each Linear user, you can:
- Map the user to an existing Shortcut member.
- Invite the user to Shortcut.
- Leave the user unmapped.
An unmapped user becomes a disabled placeholder member with their Linear name. Their Stories, Comments, and other activity stay attributed to them, and you can invite them after the import.
What gets imported from Linear
| Linear | Shortcut | Notes |
|---|---|---|
| Issue title | Story name | |
| Issue description | Story description | Markdown is kept. Shortcut adds a line that links back to the Linear issue. |
Issue ID, for example ENG-123 | Story external ID | The Linear issue URL is also added as an external link. |
| Workflow state | Workflow State | Uses your mapping. |
| Labels | Labels | Colors are kept. A label in a group is named Group: Label. |
| A label named Bug, Feature, or Chore | Story type | Stories without one of these labels are Features. |
| Assignee | Owner | |
| Creator | Requester | |
| Subscribers | Followers | |
| Comments | Comments | Threaded replies are flattened into one list, in the order they were posted. |
| Estimate | Estimate | Rounded to a whole number of points. |
| Priority Urgent, High, Medium, Low | Priority Highest, High, Medium, Low | Uses the built-in Priority field. If the field is off, or one of these values is renamed or turned off, those Stories get no Priority. |
| Due date | Deadline | |
| Started, completed, and canceled dates | Started and completed dates | A canceled date becomes the Story’s completed date. |
| Projects | Epics | The project lead becomes the Epic Owner, the project creator becomes the Requester, and project members become Followers. The start date becomes the planned start date, and the target date becomes the Epic deadline. |
| Project status | Epic state | Backlog and Planned become Unstarted. Started and Paused become Started. Completed and Canceled become Done. |
| An issue’s project | The Story’s Epic | |
| Cycles | Iterations | Only when Iterations are on. Cycle dates use the Linear team’s timezone. |
| Sub-issues | Sub-tasks | See Sub-issues. |
| Blocks, Duplicate, and Related relations | Story links | These become “blocks”, “duplicates”, and “relates to” links. |
| Link attachments, such as GitHub pull requests | External links | |
| Uploaded files and images | Files on the Story | Covers uploads in descriptions, comments, and attachments. Links in the text point at the copy in Shortcut. |
| Archived issues | Stories | Archived issues are imported like any other issue. |
Shortcut does not import deleted issues, which are issues in Linear’s trash.
Sub-issues
Shortcut Sub-tasks have one level, and Linear sub-issues can nest. The importer places every sub-issue, at any depth, under its top-level issue.
Each Story can hold up to 100 Sub-tasks. When a top-level issue has more than 100 sub-issues, the importer adds the first 100 by creation date as Sub-tasks. Each remaining sub-issue stays a regular Story with a “relates to” link to the top-level Story.
If a sub-issue’s parent is in a different Linear team, the sub-issue is imported as a regular Story.
People, integrations, and bots
When an integration or a bot acted in Linear, the importer credits a placeholder member named after the bot, with ” (bot)” at the end. For example, a comment posted from Slack comes from Slack (bot). This covers Linear’s own onboarding issues, integrations such as Slack and GitHub, and Linear agents.
An issue that a bot created gets you, the Admin who runs the import, as its Requester.
What is not imported
The importer does not bring over:
- Initiatives.
- Project milestones and project updates.
- Documents.
- Customer requests.
- Views.
- Notifications.
- Linear’s “similar issue” suggestions.
Epic descriptions keep their text, but links to files uploaded in Linear still point at Linear. The importer attaches files to Stories only.
Files larger than 50 MB are not copied, which is the same limit as for a file attached to a Story in Shortcut. Links to those files still point at Linear.
How long an import takes
The importer stays within the hourly limits that Linear sets for each API key, and it leaves part of each limit unused so that other tools on the same key keep working. When an import reaches the limit, it waits for the limit to reset and then continues. Large teams take longer to import.
Undo an import
To undo an import, go to the Past Imports tab in Settings > Import / Sync and click Undo next to the import. Undoing deletes every Story the import created, including Stories that someone edited after the import.
Run a second import
Each import creates new Stories. Importing the same Linear team again creates a duplicate of every Story. To start over, undo the first import, then import again.
In a second import into the same Workspace, each Linear user from an earlier import is already mapped to the same Shortcut member as before. You cannot change these mappings.