Branch and PR conventions that survive contact with Linear
Linear will move issues through your workflow on its own, but only for branches that carry the identifier. Here is how the matching actually works and how to catch the work it never sees.
Half your team copies the branch name out of Linear and their issues glide from In Progress to Done without anyone touching a dropdown. The other half types git checkout -b login-fix, ships it, and the issue sits in Todo until someone notices at the end of the sprint. Same workflow, same repository, completely different data.
This is the easiest of these problems to fix, because Linear is unusually well designed for it. The identifier does almost all the work.
Short identifiers, large consequences
Linear issues have short identifiers built from a team prefix and a number: ENG-412, PLAT-88. That is a small design decision with large consequences. The identifier is unique across the workspace, short enough to type from memory, distinctive enough to match with a regular expression, and stable enough to still resolve years later. Trackers that identify work only by a long numeric id or a URL cannot do any of what follows.
Linear’s git integration watches for that identifier and links on sight. Put it in a branch name and Linear attaches the branch to the issue. Open a pull request from that branch and the pull request is attached too, appearing on the issue with its current state. Merge it and Linear can move the issue to the state you have mapped for merged work. The states involved are configurable per team, and the mapping between pull request events and workflow states is a workspace setting rather than something hardcoded, so check yours before you assume what “merged” does.
Linear also recognises the identifier in pull request titles and descriptions, and supports closing phrases there. This is the escape hatch for the branch you already created before you thought about it: you do not have to rename the branch, you can put the identifier in the title and get the same link.
The piece most teams skip is that Linear will generate the branch name for you. From an issue, you can copy a git branch name that already contains the identifier and a slug of the title, and the exact format is configurable so it can match whatever shape your team already prefers. Two keystrokes and a paste, and the convention has enforced itself.
Automation only moves issues that already exist
Automation only moves issues that exist. This is the important one and it is easy to miss precisely because Linear’s automation is so good. If an engineer opens a pull request with no issue behind it, nothing goes wrong. There is no error, no warning, no unlinked item in a queue. The work simply never appears in Linear at all. Your board looks clean because the missing work is missing from the thing you would use to notice it.
Identifiers are per team. If work moves between teams, the identifier can change, and old references in commit history point at the previous form. Linear handles redirection for the common cases, but before you rely on historical matching in a script, test what happens to an issue you have actually moved. Do not take a blog post’s word for it, including this one.
Regex matching is not free of false positives. A pattern like [A-Z]+-\d+ will happily match UTF-8, an ISO date fragment, an AWS instance type, and any Jira key left over from a migration. If you are scripting anything against branch names, constrain the pattern to the team prefixes that actually exist in your workspace rather than matching the general shape.
The state mapping is a blunt instrument. Merging a pull request tells you code landed on a branch. It does not tell you the change is deployed, verified, or that the acceptance criteria hold. If your merged state is called Done, your board is claiming something stronger than the evidence supports. That is a workflow design question, not a naming one, but the naming convention is what makes the wrong claim automatic.
Make copying the branch name the documented start of work
Make copying the branch name the documented start of work. Not “use this format”, which is a rule people simulate from memory and get subtly wrong. “Copy it from the issue”, which is a mechanical action that cannot be got wrong. Set the branch name format once at the workspace level to whatever your team already writes, so the copied name looks native rather than imposed.
Give people the recovery path explicitly. Most conventions fail because there is no clean way back once you have deviated. Tell everyone, in the same sentence as the rule, that if the branch is already named something else they can put the identifier in the pull request title and get the identical result. That single sentence converts a large share of would-be orphans.
Then measure the orphans, because Linear cannot show you what it never received. Query your git host for pull requests merged in the last month, match titles and branch names against your real team prefixes, and count the ones that match nothing. That number is the only honest measure of whether your convention works, and it is a short script against your host’s API rather than anything exotic.
The metric to track is not how many issues have a linked pull request. Linear's automation makes that number look good almost immediately. Track the reverse: how many merged pull requests resolve to no issue at all. That is the work your planning tool has never seen.
If the orphan rate stays high, add a non-blocking check. A job in your pull request pipeline that matches the title and branch name against your prefixes and posts a comment when neither matches. Comment, not fail. A failing build for a missing identifier gets an identifier pasted in from the nearest open issue, which is worse than no link because it is a wrong link that looks right.
Where teams need more than this is usually when work spans several repositories, or several trackers after an acquisition, and the question becomes “what shipped this fortnight” across all of them at once. That aggregation is genuinely awkward to script and stay on top of, and it is the problem GroundTruth exists to solve, with full two-way sync for Linear. But if you are one team on one repository, the steps above are the whole answer and you do not need anything else.
Where this breaks down
A perfect linking rate can still describe nothing. Every pull request can carry a valid identifier while the issues themselves say “fix the thing” and carry no criteria. Linking makes work traceable. It does not make it legible.
Automatic state transitions can be actively misleading. Once merging moves an issue to Done, your cycle time metrics measure time to merge, not time to value. Teams that deploy weekly from a trunk that merges hourly are measuring the wrong interval and will not notice, because the board is confidently green.
Some work should not have an issue. Reverts, dependency bumps, a fixed typo. Chasing a hundred percent linking rate produces issues created purely to satisfy the metric, which pollutes the tracker you were trying to make trustworthy. Define your exemptions before you define your target.
Small colocated teams may not need any of this. If five people sit together and ship twice a day, the tracker is a formality and the naming convention is overhead. The costs here are real and they land on people who feel them daily. Be sure the traceability is actually worth something to someone before you ask for it.
The takeaway
Linear gets branch naming closer to correct out of the box than almost anything else, because the identifier is short, unique and stable, and because the tool will write the branch name for you. Use the generated name, tell people the pull request title is a valid fallback, and then spend your attention on the one thing the automation cannot show you.
If you do one thing this week: count merged pull requests whose branch and title match none of your team prefixes. Linear’s board will never contain that number, and it is the one that matters.