How to Link GitHub Pull Requests to Jira Issues

Your delivery data lives in two places and neither tells the whole story. GitHub knows when a pull request opened, who reviewed it, and when it merged. Jira knows when someone decided the work mattered. The gap between those two moments is usually the largest and least examined part of your lead time. This guide covers how to close it: the exact naming conventions that make linking work, the one convention that silently fails, and what the joined-up data shows that neither tool shows alone.

Why link pull requests to issues at all?

Measure a pull request on its own and you measure the part of delivery that is already going well. By the time a PR exists, someone has decided what to build, worked out how, and written the code. The clock you can see starts late.

Linking closes that gap. When a pull request resolves to an issue, the issue's creation timestamp becomes the real start of the work, and the stretch between ticket creation and the first commit becomes visible as a distinct phase. On plenty of teams that phase is larger than coding and review combined, and it is invisible in every GitHub-only report.

"A pull request measures the part of delivery that is already going well. The expensive part happened before anyone opened it."

The second thing it buys you is honest categorization. Work type classification runs off GitHub labels first, but label discipline decays - people forget, and nobody backfills. A linked issue gives a second source: the issue's own labels and type can fill in the work type when a pull request carries no label of its own. For the fuller picture on how that classification feeds reporting, see our guide to KTLO versus innovation investment.

How does the linking actually work?

There is no plugin to install and nothing to configure per repository. After Jira is connected, every pull request is scanned for text matching a Jira issue key - a project prefix of two to fifteen letters, a hyphen, then a number. ENG-412, PLATFORM-7 and AB-1 all match. Matching is case insensitive, and a single pull request can link to several issues if it references more than one.

Two fields are scanned, and only two:

That description row is worth pausing on, because "reference the ticket in the PR body" is a common house style and it produces a link rate of zero with no error anywhere. If your team writes Closes ENG-412 in the description and nothing else, every one of those pull requests looks unlinked. The fix is a one-line change to how branches are named, and it applies to every future PR without anyone remembering anything.

What naming conventions make linking reliable?

Put the key in the branch name. Branches are created once and the key rides along for the life of the work, whereas titles get rewritten halfway through a review and the key quietly disappears with them.

# Reliable - key in the branch name
git checkout -b feature/ENG-412-retry-webhooks
git checkout -b fix/PLATFORM-88-null-pointer
git checkout -b ENG-1204-add-audit-log

# Also works - key at the start of the PR title
"ENG-412: retry failed webhooks"
"[PLATFORM-88] fix null pointer in sync"

# Does not link - key only in the body
"Retry failed webhooks"        # title has no key
Closes ENG-412                 # description is not scanned

Two habits worth adopting alongside it. First, create the branch from the Jira issue view where you can - Jira offers the branch name with the key already in it, which removes the chance of a typo. Second, if you use a pull request template, put the key placeholder in the title field rather than the body, so the convention is visible at the moment someone opens the PR.

Teams running trunk-based development with short-lived branches get the best results here, since one branch maps cleanly to one issue. Where a single long-lived branch accumulates several tickets, expect a many-to-one link and interpret the phase timings with more care. Our guide on how branching strategy affects your metrics covers that trade-off.

What does linking unlock?

Three things become measurable that GitHub alone cannot show.

The planning phase. Issue created to first commit - how long work waited after someone decided it mattered. This lands as a distinct phase on the lead time breakdown alongside coding, waiting, review and merge, and it is the phase most likely to surprise people. If you are new to phase-level analysis, start with our cycle time breakdown guide.

Time in status. Because Jira status change history syncs, not just the current status, you can see how long issues sit in each workflow state. This is where "blocked" and "in review" queues show up as durations rather than as counts on a board.

Link coverage as a data quality signal. The proportion of merged pull requests that resolved to an issue is itself a useful number. Low coverage usually means a naming convention problem rather than untracked work, and it tells you how much to trust any issue-derived figure sitting next to it.

"Link coverage is not a vanity metric. It is the confidence interval on every other number derived from your issues."

What does not come across?

Being straight about the boundaries saves you evaluating this against the wrong expectations. The sync pulls issue key, title, description, type, status, priority, labels, assignee, project, fix version, the created, updated and resolved timestamps, and the full status change history.

It does not pull story points, sprints, epics, worklogs, time tracking, comments or components. That is a deliberate boundary rather than a roadmap gap: the aim is delivery flow analysis grounded in what actually happened in the repository, not a second rendering of your Jira board. If your question is "how did this sprint go against its commitment", Jira already answers that better than any analytics layer will. If your question is "where does our time actually go between deciding and shipping", that is what this data is for.

"Two systems disagreeing is not a data problem. It is usually the first honest look at how long work waits before anyone touches it."

On first connection, issues sync from roughly 400 days back, then incrementally on a schedule. Historic pull requests get linked as part of that backfill, so you are not starting from an empty chart.

Why are pull requests not linking?

Work through these in order. Most low-coverage cases are the first one.

1. The key is only in the PR description. Check a handful of unlinked pull requests. If the key appears in the body but not the branch or title, that is your answer, and it is a convention fix rather than a configuration one.
2. The project is outside the sync scope. Projects are picked up from keys seen on your pull requests. A team using a project that has never appeared in a branch name or title will not have its issues synced.
3. The pull request predates the lookback window. Anything older than the backfill horizon will not retroactively link.
4. The key format is unusual. Project prefixes shorter than two characters or longer than fifteen will not match.

Check the link coverage figure before concluding the integration is broken. A team at 85 percent coverage with a stable convention is in good shape; the missing 15 percent is usually dependency bumps and other automated pull requests that never had a ticket in the first place.

Getting started

Connect Jira from the integrations page, then agree one branch naming convention and write it down somewhere the team will see it. Give it a week, look at link coverage, and fix the convention rather than the tooling if the number is low. Once coverage is stable, the planning phase on the lead time breakdown is the first place worth looking - it is the number most teams have never measured, and it is frequently the largest.

If you have not yet joined up delivery reporting across the two systems, our guide on progress tracking without Jira access covers what is possible from GitHub alone, which is a useful baseline for judging what linking adds.