Migration guide

Before starting the migration process, you’ll need to make several key decisions that will shape your approach:

• Will you import existing issues or start fresh?
• Should teams follow standardized workflows or maintain autonomy?
• What’s your timeline and communication plan?

This guide walks through each decision, outlining the trade-offs and best practices we’ve learned from hundreds of successful migrations.

Many teams use the migration to Linear as an opportunity to start fresh and leave their old issues behind. Other teams import their existing issues from other tools for reference or to finish a sprint. Your preference will inform your migration plan.

Import your issues

Use the Importer to pull in-flight issues into Linear and map them to appropriate teams. Linear offers native importers for GitHub Issues, Jira, Asana, Shortcut, and Trello. Alternatively, you can import a CSV with issue data.

If you're using Jira or GitHub Issues and not yet ready to fully import your data, you can enable two-way sync while trialing or transitioning to Linear. The Jira integration and GitHub Issues integration keep Linear in sync with your current tool, so that new issues created live in both places.

Why companies import

Organizations may need to preserve important data from their previous issue tracker, whether for active tasks or future reference. It could also be the case that several teams are working on high-priority projects that are mid-cycle.

Start fresh

Migration is your chance to move forward with intention, not historical baggage. The switch to Linear can be an opportunity for a clean slate.

Why companies start fresh

For an operational reset, get your team members accustomed to Linear terminology and methodology, while keeping them focused on building and shipping. This is opposed to balancing old conventions in imported issues and projects alongside net new issues.

There are two approaches when it comes to setting up Linear.

Standardized workflows

In a prescriptive approach, functions such as technical program management, engineering ops, or IT standardize the Linear workspace and team settings to create a shared way of working. Organizations that follow this path frequently map their backlog and in-progress work to the new way of working in Linear.

The benefits of standardization

Reporting is easier when every team uses the same labels, estimations, templates, statuses, and SLAs. If you know you’re going to need specific reports, for example, it’s worth being intentional about how you structure workflows in Linear.

Standardizing how teams work can also facilitate alignment by establishing a company-wide cadence. Linear cycles get everyone moving at the same speed and shipping on the same timelines.

Autonomous teams

Alternative to a standardized approach, some organizations prefer to give each team autonomy over how they work. Organizations that follow this path typically enable their teams to configure Linear independently.

The benefits of autonomy for teams

Each team can customize their Linear workspace to stay focused and productive. We find that teams that have more freedom in their setup are more likely to fully adopt Linear, though producing reports is not as straightforward when working styles aren’t standardized.

Building an internal transition guide will help you think through each part of the migration and keep everyone on track.

Document the process

Approach

Spell out how you are approaching your migration (standardized vs. autonomous; import vs. starting fresh) and your reasons for doing so.

Since this internal guide will be distributed to teams that did not participate in the pilot, include high-level findings from the trial and state the main goal(s) of switching to Linear. Include a few data points or quotes from real team members to bolster your message.

Timeline

Work with your organization’s leaders to set a go-live date based on your approach to migration and configuration, keeping in mind any renewal dates for the tools Linear is replacing. If the autonomous approach is preferred, we recommend giving teams up to 6 weeks to configure their workspace and team settings.

Training

Run a Linear demo for your organization and share self-serve onboarding resources to teams in advance of the rollout, such as links to Linear docs and best practices. If you plan to use Asks to intake issues from non-Linear users, organize an onboarding session to educate them on how to use Asks in Slack to submit a request.

Communication

Create a Slack channel for Linear-related questions to support your teammates throughout the migration. The Slack channel creates a centralized home for the resources you’re creating, and gives new users a place to ask questions or request support.

Apprehension comes with change. Put your team members at ease by letting them know when Linear is coming and how the migration will work. Keep your announcement short and actionable to increase engagement with the migration.

Use this template as a baseline:

Provision users

If you are coming from a prior tool and bringing data over, provision your Linear users. Linear’s native importers will match existing Linear users to the users you are importing. Ideally, users already exist in both services with the same email address and have linked their accounts in Settings > Integrations so that creators, assignees, mentions, and comments are imported properly.

Create your teams

Issues in Linear are organized by team. Linear will automatically create a default team with the same name as your workspace, but you can create more teams to group employees who work together frequently or who work on a specific area or feature. We recommend starting with fewer teams and then adding more (and moving necessary issues) over time.

Import data (if applicable)

Note: You must be a Linear Admin to run an import.

1. Navigate to Settings > Workspace > Import/Export and select your current issue tracker.
2. Select the issues you want to import and the Linear team to import them to.
3. Review fetched data.
4. Map the users the Importer found in your current issue tracker.
5. Confirm your selections. Click Finish.

Migrate your integrations

Most issue trackers are connected to upstream or downstream tools. Work with your Linear admins and those responsible for other internal tools to get each integration up and running. Below are a few examples of common integrations with Linear:

• Slack
  To create issues and receive notifications
• Customer Support Tools
  To intake bugs and feature requests from the frontlines (such as Zendesk, Front, or Intercom)
• GitHub
  Linear’s native workflow automations and issue syncing for OSS.
• Triage Responsibility
  Create ownership over triage; supporting PagerDuty, incident.io and Opsgenie rotations
• Google Calendar
  Let teammates know if you are away or OOO

Sunset your previous tool

Notify your previous service provider that you are no longer using their services once you’ve made the decision to move over to Linear. Work with your internal tools team to shut off access to the tool or put it in read only mode.

Once migrated, send a message to the team Slack channel letting teammates know that your previous issue tracker is no longer available.

Enable users

Follow your training plan and schedule additional enablement sessions as needed. If you’re taking an autonomous approach to configuration, some teams may want extra guidance when configuring workspace and team settings.

Share the Linear Method and Getting Started Documentation in your internal operations documentation for easy reference.

Learn how to hone your Linear pitch or run a pilot to strengthen your case for Linear.