Linear GitHub Integration: PR Links & Issue Status
The GitHub-Linear integration is the keystone of a modern engineering workflow. Engineers create branches named with the Linear issue ID, work on the code, and when they open a pull request, Linear automatically links the PR to the issue and updates its status. PMs see engineering progress in Linear without asking engineers for updates. Engineers see issue context in GitHub without switching tools.
This guide covers the complete GitHub-Linear integration setup from installation through workflow automation.
Planning a sprint in Linear? Turn your spec into dependency-ordered tickets.
Paste the feature or spec. Vantage pulls out the requirements and breaks them into tickets, ordered by what blocks what, ready to groom with your team.
How this works
- We save what you typed. No AI runs on this page.
- You create a free account.
- Vantage builds a PRD and dependency-ordered tickets from it inside your own workspace.
Why ask for an account? We’re a small team, and a full generation runs a multi-step AI pipeline that costs us real money. So we tie it to a free account instead of running it anonymously. You also get to keep the result and edit it.
Your text is only used to create your project, and it stays private to your account. If you don’t sign up, we delete it after 7 days. Privacy policy
Step-by-step guide
Install the GitHub integration in Linear
In Linear, go to Settings > Integrations > GitHub. Click Enable. Authorize Linear to access your GitHub organization. Select the repositories to connect (you can connect all repos or specific ones). Linear will now listen for branch names and PR events that reference Linear issue IDs.
Establish the branch naming convention
Linear auto-generates branch names for each issue. When you open a Linear issue, use Copy git branch name (Cmd/Ctrl+Shift+.) to copy the configured branch format, including the issue ID. Engineers run git checkout -b [paste branch name] to create the correctly named branch.
Configure auto-status updates
Configure GitHub workflow automations in team settings. Map PR events to your chosen issue statuses. Creating a local branch alone does not confirm work has started; copying a branch name has a separate optional automation.
Link PRs to issues via commits
Add "Fixes ENG-123" to a PR title or description to link an issue. Commit linking requires its separate integration setup. Closing, non-closing, and relation keywords have different effects; test your chosen workflow.
View PR status in Linear
In any Linear issue, the PR panel (right sidebar) shows: PR title, branch name, review status (approved/changes requested/pending), CI status (passing/failing), and merge status. PMs can see whether the PR is approved and CI is passing without accessing GitHub directly.
Distinguish merged code from deployed code
A merged PR does not prove a production deployment succeeded. Check the deployment system before marking work live. Branch-specific merge rules can update issue statuses, but they do not verify production health.
Create a Linear Git workflow guide for the team
Document the team's Linear-GitHub workflow in a Linear document: (1) Create or assign a Linear issue, (2) Copy the branch name from Linear, (3) Create the branch, (4) Write code, (5) Open PR — Linear automatically links and updates status. Share this in your engineering onboarding doc so every new engineer follows the same flow from day one.
Common mistakes
Not setting the branch naming convention
Branch names are one linking method. PR titles or descriptions can also link issues using an ID or supported keyword. Agree on one convention so reviewers can find the issue.
Connecting the wrong repositories
Connecting all GitHub repos including internal tools and ops scripts creates noise in Linear. Connect only the repositories that contain product code linked to Linear issues.
Ignoring CI status in Linear
The CI status badge on Linear issues (red/green from GitHub Actions) is actionable data. Engineers should not move issues to Done if CI is red. Add this to the definition of done: PR merged AND CI passing.
Tips
Use Linear's keyboard shortcut to copy branch names — it is much faster than typing the issue ID manually
Add a GitHub Actions step that comments the Linear issue URL on every PR for easy navigation back to the Linear issue
Review the linked pull request before assuming an issue is ready to merge
Use the Linear API to pull PR cycle time data for engineering velocity analysis
How Vantage helps
Vantage's GitHub integration lets PMs query the codebase as product context for PRD generation. When Linear issues are linked to GitHub PRs via this integration, PMs can query relevant repository context when reviewing future requirements; generated conclusions still need engineering review.