Modern project management tool built for software teams with fast keyboard-driven interface and automated workflows.
Full ReviewThe GitHub and Linear integration connects your code repository with Linear's modern project tracking tool, enabling automatic linking between Linear issues and GitHub pull requests, branches, and commits. Linear provides a native GitHub integration that is deeply embedded into the product, making it one of the most seamless issue-tracker-to-repository connections available.
Once connected, referencing a Linear issue identifier (like ENG-123) in a GitHub branch name, commit message, or pull request automatically links the code change to the Linear issue. Linear updates issue status based on GitHub activity — issues automatically move to "In Progress" when a branch is created and to "Done" when a pull request is merged. Pull request status, review state, and CI checks are visible directly on the Linear issue.
The result is an effortless feedback loop between code and project management. Developers rarely need to manually update issue status in Linear because the GitHub integration handles transitions automatically. Product managers and engineering leads get real-time visibility into development progress without interrupting developers.
In Linear, click Settings (gear icon) in the bottom left corner. Navigate to Integrations in the settings sidebar. Find GitHub in the list of available integrations and click Connect. Linear supports both GitHub.com and GitHub Enterprise Cloud.
Click Connect to GitHub. You will be redirected to GitHub's authorization page. Select the GitHub organization or personal account you want to connect. Choose which repositories to grant Linear access to: All repositories or Only select repositories. Click Install & Authorize. You will be redirected back to Linear with the connection confirmed.
After connecting, Linear shows a configuration page where you map Linear teams to GitHub repositories. Select a Linear team (e.g., "Engineering") and assign the GitHub repositories that team works on. This mapping ensures that when pull requests reference issues from a specific team, the links are properly associated. You can assign multiple repositories to a single team.
In the GitHub integration settings, enable automatic workflow state transitions. The default configuration is: when a branch is created with a Linear issue ID, move the issue to In Progress; when a pull request is opened, move to In Review; when a pull request is merged, move to Done. You can customize which Linear states these map to based on your team's workflow. Toggle each transition on or off as needed.
Reference Linear issue identifiers in your GitHub workflow. Linear uses identifiers in the format TEAM-123 (e.g., ENG-42). Include the identifier in branch names (eng-42-user-authentication), commit messages (ENG-42: implement OAuth login), and pull request titles ([ENG-42] Add user authentication). Linear detects these references automatically. Note: Linear identifiers are case-insensitive in branch names.
Linear provides a convenient shortcut for creating correctly formatted branch names. On any Linear issue, press Cmd+Shift+. (Mac) or Ctrl+Shift+. (Windows/Linux), or click the issue menu and select Copy git branch name. This copies a pre-formatted branch name like username/eng-42-issue-title that you can paste directly into your git checkout command.
Create a test issue in Linear. Copy the branch name from the issue, create the branch in GitHub, make a commit, and open a pull request. Check the Linear issue to verify: the branch appears in the issue's activity feed, the issue status automatically changed, and the pull request status (open, review pending, merged) is displayed on the issue.
The integration supports per-team configuration of auto-close behavior (whether merging a PR closes the Linear issue or just moves it to a "Done" state), branch naming format preferences, and which GitHub events trigger state transitions. You can also configure whether Linear should create GitHub pull request comments with issue information. Multiple GitHub organizations can be connected to a single Linear workspace.
| Data | Direction | Frequency |
|---|---|---|
| Branch creation events | GitHub to Linear | Real-time |
| Pull request status and reviews | GitHub to Linear | Real-time |
| Commit references | GitHub to Linear | Real-time |
| CI/CD check status | GitHub to Linear | Real-time |
| Issue state transitions | GitHub events trigger Linear updates | Real-time |
Ensure the issue identifier format matches exactly (TEAM-123). Check that the GitHub repository is mapped to the correct Linear team in the integration settings. If the repository is not mapped to any team, references will not be detected. Also verify the Linear GitHub app still has access to the repository in GitHub's Settings > Applications > Installed GitHub Apps.
Check the integration settings in Linear to confirm auto-transitions are enabled. Verify the target workflow states exist in your team's workflow configuration (under Settings > Teams > [Team] > Workflow). If you have customized your workflow states, the default transition mappings may not match your state names.
If two Linear teams have overlapping issue ID prefixes, the integration may link to the wrong team's issue. This is rare since Linear enforces unique team identifiers, but check your team-to-repository mappings if cross-linking occurs.
For advanced workflows, use Linear's API and webhooks alongside the GitHub integration to build custom automation. Linear's GraphQL API supports creating issues, updating status, and querying project data programmatically. Combine this with GitHub Actions to create sophisticated CI/CD-to-project-management workflows — for example, automatically creating a Linear issue when a GitHub Actions deployment fails, or posting deployment URLs as comments on Linear issues when a staging deploy completes successfully.
