> 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 planning tickets (e.g., Jira issues, GitHub Issues, Azure DevOps work items) by scanning for ticket keys in your PR metadata. This linking is what powers the "Linked Task", "Ticket Without PR", and "Unlinked Pull Request" categories across dashboards.

## How Linking Works

When Logilica imports a pull request, it scans **four locations** for ticket keys in the format `PROJECT-123` (one or more letters, a hyphen, then one or more digits):

| Location                  | Example                               | Pattern                                 |
| ------------------------- | ------------------------------------- | --------------------------------------- |
| **Branch name**           | `feature/LPAV-1056-add-login`         | Extracted between separators (`-`, `_`) |
| **PR title**              | `[LPAV-1056] Fix authentication bug`  | Word boundary matching                  |
| **PR description / body** | `Closes LPAV-1056, resolves LPAV-731` | Word boundary matching                  |
| **Commit messages**       | `LPAV-1056: update error handling`    | Word boundary matching                  |

All extracted keys are **normalised to uppercase** and **deduplicated**, so `lpav-1056` and `LPAV-1056` are treated as 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.

## 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

* **Ticket key must match the format `LETTERS-DIGITS`** — keys like `#123` or `GH-issue-45` will not be detected
* **The ticket must exist in a connected planning tool** — if the project key doesn't match any imported planning project, the link won't be established in dashboards
* **Keys are case-insensitive** — `lpav-1056`, `LPAV-1056`, and `Lpav-1056` all resolve to the same ticket
* **Don't rely on a single location** — including the key in both the branch name and PR title provides redundancy

## 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.logilica.com/integration/linking-pull-requests-and-tickets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.