Importing from GitHub Issues

Import issues from GitHub repositories to Linear teams.

Data included in the import⁠

Considerations before importing⁠

There are functionalities offered when importing from GitHub that you may wish to know about in advance, as they'll affect decisions you make before or during your import

Syncing changes back to GitHub Issues⁠

If your individual team is moving to Linear and your broader organization is still using GitHub issues, GitHub Issues sync can maintain alignment between the tools.

This sync feature will keep most issue properties matched between the original issue in GitHub, and the imported issue in Linear. Optionally, choose to enable bi-directional sync so that issues created in Linear will also sync to GitHub (otherwise, only issues created in GitHub will sync to Linear.)

GitHub 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 within a team to GitHub, or select a different repository to sync to except by editing this setting.

For best performance in syncing fields like assignee and creator, individual Linear users should also connect their personal GitHub accounts to Linear in integration settings prior to import as well. Please see the Mapping GitHub users section for more information on this.

Running an import from a synced GitHub project will import those issues as synced automatically.

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 > Integrations > GitHub.

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.

Running the import⁠

When you're ready to import, you can do so by heading to Linear's Import/Export settings. Please note that you must be a Linear Admin to run an import.

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 > Workspace > Import/Export, and choose GitHub
2. Click next to Connected organizations, and OAuth into GitHub
3. Choose the organization you wish to import from
4. Choose which repos to give the importer access to, and select Install
5. You will be redirected back to Linear, and can now select the repos you wish to import

Once an organization is connected, you can proceed with a standard import.

1. Navigate to Settings > Workspace > Import/Export, and choose GitHub
2. Choose a repo or repos to import from, whether to import Closed issues from GitHub, and a Linear team to import to. If you import Closed issues, they will import to 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.
3. Review the fetched data
4. Choose whether to import your stale issues to the archive. Stale issues are open GitHub issues that have not been updated in over six months.
5. Choose whether to sync with GitHub Issues. If this option is disabled but you wish to use it, exit the importer to set up your sync mappings then check this box to continue importing.
6. Map your users. For each user found, choose not to import them, map them to an existing user in your Linear workspace or invite them via email.
7. 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.

If you run into issues or need further assistance, please let us know at support@linear.app.