Importing from GitHub Issues

This guide explains how to migrate from GitHub Issues to Linear, covering both approaches—starting fresh and importing historical data. We will walk through the preparation, execution, and cleanup phases of migration to ensure a smooth transition.

Migration Approaches⁠

Bringing historical GitHub Issues into Linear offers several advantages. It preserves valuable context around feature development and bug fixes, maintains all discussions in one place, and provides continuity for in-progress work. Historical data also enables comprehensive reporting and more accurate future estimations based on past performance.

However, starting fresh in Linear has its own benefits. It gives teams a clean slate to implement improved workflows without the baggage of outdated processes. The migration process is much simpler with fewer decisions to be made and conflicts to resolve. Teams can establish practices from day one without inheriting messy historical data.

Many teams choose a middle ground—importing only recent and in-progress issues while keeping the rest in GitHub as a historical archive. This approach balances maintaining critical context while using the migration as an opportunity to clean up and prioritize the backlog. Your specific needs, the quality of your GitHub data, and how important historical context is to your ongoing work should guide your decision.

Pre-Migration Planning⁠

1. Set up Linear teams for each functional group that will be working in Linear.
   Provision users and add them to appropriate teams. Linear supports SCIM Group Push.
2. Align workflows by creating states in Linear that match what teams use in GitHub. Similar state names will automatically map during import.
3. Develop a label cleanup strategy Clean up unused labels in GitHub and plan which labels should be team-specific vs. workspace-wide.
4. Enable key Linear features like Triage, Estimates, Cycles.
5. Define use cases for GitHub Sync either unidirectional or bidirectional. Refer to GitHub Sync Options.

Important Considerations⁠

• Status Mapping: In GitHub, issues are simply "open" or "closed". If an issue is unstarted or started in Linear, it's considered "open" in GitHub. If completed in Linear, it's considered "closed" in GitHub.
• User Connections: For comments and actions to be properly attributed during sync, users need to connect their GitHub accounts in Linear (Preferences > GitHub > Connect Personal Account).
• Sync Limitations: The sync doesn't attempt to replicate all features between the systems, focusing instead on core issue tracking functionality.
• Transition Tool: Bidirectional sync is generally recommended as a temporary transition tool rather than a permanent solution, due to its limitations and potential for confusion.
• Multiple Repositories: You can sync multiple GitHub repositories to a single Linear team, but each Linear team's issues can only sync with a single GitHub repository.

This sync capability allows teams to gradually transition to Linear while maintaining critical GitHub workflows, but it's generally best to eventually consolidate to a single system for clarity and efficiency.

Running the import⁠

Prerequisites⁠

• You must be a Linear Admin to perform imports
• The first import requires installing the Linear Data importer GitHub app
• GitHub organization admin access or approval may be required

Import process⁠

Setting up an import for the first time⁠

The first time you run an import from a new GitHub organization, you'll need to install the Linear Data importer as a GitHub app. This step may require approval from an Admin in your GitHub organization.

1. Navigate to Settings > Administration > Import/Export
2. Select GitHub as the source
3. Click next to "Connected organizations" and authenticate into GitHub
4. Choose the organization you wish to import from
5. Select the repositories to give the importer access to
6. Click Install
7. You will be redirected back to Linear, and can now select the repos you wish to import

Importing once you connected your GitHub organization ⁠

1. Navigate to Settings > Administration > Import/Export
2. Select GitHub as the source
3. Select a repo or repos to import from
4. Choose the Linear team to import into.
5. Decide whether to import data for closed issues.
6. Review the fetched data
7. Select if you want to import closed issues into your team's archive.
   This archive is accessible from the dropdown menu on the team in your Linear sidebar. Archived issues can be restored at any time.
8. Choose whether to sync changes from Linear back to GitHub Issues.
9. Map your users.
10. Confirm your selections, and select Finish to start the import.

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.

Data included in the import⁠

Syncing issues⁠

The GitHub Issues Importer will sync imported issues bidirectionally.

Mapping GitHub users to Linear⁠

The importer will attempt to match existing users in Linear to those you're importing from GitHub. The optimal case is for users to already exist in both services with the same email address, and to have linked their GitHub accounts in Settings > Connected accounts.

That said, often this is not the case in practice.

1. If a user is not yet in Linear, but has a valid email address in GitHub: User will be treated as an external user and will be attributed as author of issues and comments, but not as the assignee
2. User's email address is unavailable: We cannot match these users. But if the user links their Linear and GitHub accounts in Settings > Integrations > GitHub and if the import is re-run, we might have a match.

Regardless of the scenario, re-running the import after users have joined will always help matching more users.

Post import clean-up⁠

Label Organization⁠

Promote common labels to workspace level for universal use:

1. Go to Settings > Features : Labels
2. Create a new label with the exact same name as the team label
3. Re-enter the label name in the field
4. Select Merge labels

Consider grouping related labels and removing unused ones. You can refer to the Usage column in the Label settings page.

Projects Management⁠

GitHub Projects import as Linear Projects. Add appropriate teams to each project by finding it via search, selecting the "Teams" field, and adding teams from the dropdown menu. If a project is not found, it was likely to be imported as archived.

Status Alignment⁠

If statuses didn't map correctly during import:

1. Open Team settings > Issue statuses & automations
2. Create new statuses in the correct category if needed
3. Use Views to filter issues with incorrect statuses
4. Use Cmd/Ctrl A to bulk select them and update to the correct status
5. Delete unused or duplicate statuses

Team Membership Cleanup⁠

Remove team members who were automatically added during import but aren't actually part of the functional team. The importer recognizes all contributors to issues (creators, assignees, commenters) and adds them as members.

GitHub Sync Options⁠

While the GitHub Issues Importer offers syncing on imported issues, the GitHub Issues Sync feature in Settings > Integrations > GitHub allows you to automatically create issues between Linear and GitHub and sync them.

GitHub Issues Sync relies on a mapping you provide in Settings > Integrations > GitHub between a Linear team and a GitHub repository. At this time, you cannot choose to sync only certain Linear issues to GitHub, or select a different repository to sync to except by editing this setting.

Starting Over⁠

Revert an import⁠

• For imports less than 14 days old: Go to Settings > Import/Export. Click the three dots next to the import and select Delete import.
• For imports older than 14 days, contact the team at Linear for assistance.

Note that deleting imports will remove all imported issues but not issues created directly in Linear or via GitHub sync.

Alternative: CLI Import for a flexible import⁠

For complex migrations involving custom fields:

1. Export GitHub issues to CSV
2. Format the CSV to match Linear's requirements
3. Use the Linear CLI importer

Be aware that history, links, and integrations won't migrate with this method