---
title: "Linking issues"
description: "Link a test case or run to an issue in any tracker your project uses — search, paste a link or key, link-only trackers, and unlinking with Undo."
source: "https://testorchestrator.com/docs/integrations/linking-issues"
---

# Linking issues

A test case can be linked to an issue in **any tracker your project uses** — Linear, Jira, GitHub, Azure DevOps, GitLab, Notion or a custom tracker. Open the case, click **Link issue**, then search, or paste the issue’s link or key. The same picker is used on test runs.

## The Link issue picker

On a test case, the **Linked issues** section has a **Link issue** button. It opens a small panel with a search box, a row of **tracker chips**, the results, and the **Link as** chips that choose the [link type](https://testorchestrator.com/docs/integrations/relations) (_Covers_ by default).

- **All** searches every tracker in the project at once. Results are grouped under each tracker’s logo and name, at most three per tracker, with **Show all N in …** to see the rest.
- **One chip per tracker** narrows the search to that tracker. The chips appear only when the project has two or more trackers, and your choice is remembered in this browser for the project.
- With **five or more trackers** the row shows **All**, the three trackers you link from most in this project (counted in this browser), and a **+N** menu listing every tracker with what it can do (_Search_, _By key_, _Link only_). A tracker you pick from the menu takes the third chip.

Each tracker answers on its own. With up to four trackers, a slow tracker never holds back another one’s results; with five or more, the picker asks every tracker in one request, so the results arrive together. While trackers are still searching they share one _Searching …_ line, trackers with nothing to show share one _No matches in …_ line, and a tracker that fails shows its own message — with a link to **Admin → Integrations** for admins when its connection needs renewing — while the others still list.

Use `↑` and `↓` to move through the results and `Enter` to link; `Esc` closes the panel. An issue that is already linked here shows _Linked_ and cannot be linked twice — per tracker, so `TES-12` in Linear and `TES-12` in Jira are different issues.

## What each tracker can do

Every tracker is at exactly one of three levels. The level follows from the tracker’s settings in **Admin → Integrations**; there is nothing extra to configure.

| Level | What you can do | Typical trackers |
| --- | --- | --- |
| **Search** | Search by words or key. Linked rows show the issue’s title and status, and can get an AI insight. | Linear; Jira, GitHub and Azure DevOps with a saved token |
| **By key** | No search, but a pasted key or link is fetched, so the row still shows the real title and status. | Notion with its token; a custom tracker whose API spec can fetch one issue and has _Read issues_ switched on |
| **Link only** | The issue can’t be read. You can still link it by pasting its key or link; the row says _No details_. | Trackers with no saved credentials (for example GitHub with authentication _None_), and GitLab |

In the picker, trackers that can’t be searched are named in one line — _Paste a link or key to link from …_. With a single one of them, admins also see how to make it searchable, for example **Add an API token**.

## Paste a link or key

- **A link** is matched against each tracker’s issue URL template, so it resolves to exactly one tracker, whichever chip is selected. The issue is fetched and shown first, with its real title. A key the tracker doesn’t have says so (for example _No issue PAY-999 in Jira · acme_), and a link from a tracker the project doesn’t use says that too.
- **A bare key** such as `#88` or `BUG-9` is checked against the key format of the trackers that can’t be searched. If it fits several (two GitHub repositories, say), you get one row per tracker, each with its logo — pick the one you mean. Searchable trackers find keys through their search.
- A custom tracker whose key format accepts anything (`^.+$`) is only used for a bare key when you choose that tracker in the chips, and never for text with spaces — otherwise it would claim every search.

## Link-only rows

A link to a _Link only_ tracker stores the key and the issue link, and nothing else: the row shows the key as its title and _No details_ where other rows show the status (hover it for why). It never gets an AI insight — the issue was never read, so there is nothing to summarise.

## Linked rows

Each linked row names its tracker: the key chip carries the tracker’s logo and opens the issue in that tracker. The link type is shown on the row and can be changed there; the confirmation (for example _TES-11 now counts as Defect_) has an **Undo**. When AI insights are on, rows from trackers that can be read show the insight with _from Jira_ (or the tracker it came from) on the right.

Wherever an issue key appears — linked rows on a case, the picker’s results, a run, a cycle’s Issues tab and the QA agent — hovering or focusing the key for a moment opens a [hover card](https://testorchestrator.com/docs/test-runs/run-detail#hover-card) with what is stored about the issue: its title, its status as last read, and what the link means there (on a case, the link type and _Linked 3 days ago_). It never fetches anything new; `Esc` closes it, and on a touch screen there is no card.

Linking needs no confirmation: the row appearing is the confirmation. If the tracker refuses the link, the row is removed and a message says so (for example _Couldn’t link PAY-981 — removed_).

## Unlinking and Undo

Click the **×** on a row. The row goes at once and a message reads _PAY-981 unlinked_ with **Undo**. The link is removed **about five seconds later** — or straight away if you dismiss the message, close the panel, move to another case, or leave or hide the tab.

- **Undo** (or `⌘Z` / `Ctrl+Z`) within that window brings back the **same link**: its link type, issue details and AI insight are untouched, because nothing had been removed yet.
- Picking the same issue again in the picker within that window does the same: the picker marks it _Unlinked · restore_, and choosing it brings the original link back (_PAY-981 is linked again_).
- Once the link is removed, Undo is no longer offered. To link the issue again, use the picker.
- If removing the link fails, the row comes back where it was and a message says so (_Couldn’t unlink PAY-981 — it’s back_).

> **For those few seconds, other people still see the link.** Nothing changes on the server until the window ends.

## On test runs

The runner’s **Issues** list, the fail follow-up and the Issues tab use the same picker, without the _Link as_ chips: the run’s own issues are listed first, then every tracker is searched as above, and a pasted link or key works the same way. A run link is always a **Defect**, whatever order your workspace lists its link types in. Duplicates are per target: an issue already on the run or on another case can still be linked to this case. Linking a case from a run links **its result in this run**, so the defect counts in this run only; a link on the test case itself shows in every run as a [known issue](https://testorchestrator.com/docs/test-runs/run-detail#three-origins) and is never counted.

On the run’s Issues tab, the [New issue composer](https://testorchestrator.com/docs/test-runs/run-detail#new-issue) works with every tracker too — instantly where the tracker allows it, otherwise in two steps (create it in the tracker, then find it here) — and can link an issue to the run itself with **Run only**. A run-level issue can later be [attached to cases](https://testorchestrator.com/docs/test-runs/run-detail#run-level-issues). Every issue key on a run is a link to its tracker.

## Who can do what

Seeing linked issues needs _View external references_; linking, changing the link type and unlinking need _Manage external references_. If a project has no trackers, the picker says so: admins get **Set up in Integrations**, everyone else is asked to contact a workspace admin.
