> For the complete documentation index, see [llms.txt](https://docs.logilica.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.logilica.com/integration/linking-pull-requests-and-tickets.md).

# Linking Pull Requests and Tickets

Logilica automatically links pull requests to your planning tickets, such as Jira tickets or Azure DevOps work items, by looking for the ticket ID in your pull requests. This linking is what powers the "Linked Task", "Ticket Without PR", and "Unlinked Pull Request" categories across dashboards.

## How Linking Works

Logilica looks for your ticket ID in four places, and finding it in any one of them creates the link:

| Location                  | Example                               |
| ------------------------- | ------------------------------------- |
| **Branch name**           | `feature/LPAV-1056-add-login`         |
| **PR title**              | `[LPAV-1056] Fix authentication bug`  |
| **PR description / body** | `Closes LPAV-1056, resolves LPAV-731` |
| **Commit messages**       | `LPAV-1056: update error handling`    |

Capitalisation does not matter, so `lpav-1056` and `LPAV-1056` resolve to the same ticket.

### Multiple Tickets

A single PR can link to multiple tickets. For example:

* **Branch:** `lpav-1056-lpav-1057-do-stuff` → links to `LPAV-1056` and `LPAV-1057`
* **Title:** `[LPAV-1056][LPAV-731] Do stuff` → links to `LPAV-1056` and `LPAV-731`
* **Body:** `Closes MATT-3, closes MATT-56` → links to `MATT-3` and `MATT-56`

Tickets found across all four locations are combined and deduplicated.

## Supported Connectors

This linking logic is **shared across all code connectors**:

* GitHub
* GitLab
* Bitbucket
* Azure DevOps

The same extraction rules apply regardless of which code hosting platform you use.

{% hint style="warning" %}
**Project keys within the Ticket tools must be uppercase.** A planning project whose key is lowercase or mixed case will not match. Jira enforces uppercase project keys, but YouTrack short names and Azure DevOps project names do not, so set those in uppercase if you rely on linking.
{% endhint %}

## Why Linking Matters

Linked PRs and tickets are the foundation of several Logilica metrics and views:

| Category                  | Meaning                                  | Where It Appears                                            |
| ------------------------- | ---------------------------------------- | ----------------------------------------------------------- |
| **Linked Task**           | A ticket with at least one associated PR | Activity dashboards, Team Pulse                             |
| **Ticket Without PR**     | A ticket that has no associated PR       | Highlights planning items with no code activity             |
| **Unlinked Pull Request** | A PR that doesn't match any known ticket | Highlights code work happening outside the planning process |

High numbers of unlinked PRs or tickets without PRs may indicate that the team isn't following consistent linking practices, which reduces the accuracy of cross-functional metrics like lead time and delivery tracking.

## Best Practices

### Include Ticket Keys in PR Titles

The most reliable and visible approach is to include the ticket key in the PR title:

```
LPAV-1056: Add user authentication flow
```

or

```
[LPAV-1056] Add user authentication flow
```

This ensures the link is created regardless of branch naming conventions or commit message practices.

### Use Consistent Branch Naming

If your team uses branch naming conventions, include the ticket key:

```
feature/LPAV-1056-add-authentication
bugfix/LPAV-731-fix-login-error
```

### Reference Tickets in PR Descriptions

For PRs that address multiple tickets, list them in the description:

```
This PR addresses:
- LPAV-1056: Authentication flow
- LPAV-731: Login error handling
```

### Avoid Common Pitfalls

* **Reference the ticket by its full ID** — an ID such as `LPAV-1056` is recognised, while `#123` or `GH-issue-45` is not
* **The ticket must exist in a connected planning tool** — a ticket from a project you have not connected cannot be linked
* **Don't rely on a single location** — including the key in both the branch name and PR title provides redundancy

## If Pull Requests Are Not Linking

* **Check the pull request, not just the commit.** Squash merges rewrite commit messages, so an ID that lived only in the original commits may not survive the merge. The branch name and pull request title are the most reliable places to put it.
* **Allow for the next scan.** Links appear after the next scan of your Git connector, not instantly.
* **Confirm both projects are imported.** The ticket's planning project and the repository must both be connected to Logilica.

If the ID is referenced correctly and links are still missing, contact <support@logilica.com> for help, with one example pull request URL and the ticket ID it should have matched.

## Checking Your Linking Coverage

To assess how well your team is linking PRs and tickets:

1. Navigate to the **Code Activities / Risks** dashboard and filter for "Unlinked Pull Requests"
2. Check the **Activity** views for the ratio of Linked Tasks vs. Tickets Without PR and Unlinked Pull Requests
3. A high proportion of unlinked items suggests the team needs to adopt more consistent ticket referencing

If you notice a significant number of unlinked PRs, consider adding a PR template to your repositories that prompts authors to include the ticket key.