Linear Integration

Linear is a first-class integration in TestOrchestrator. Instead of pasting an API token, a Linear workspace admin authorizes TestOrchestrator once through Linear's OAuth flow. After that, your team can search live Linear issues when linking, see an AI-written insight on each linked issue, and generate test cases straight from a Linear issue's sidebar.

Linear is a built-in integration source. Everything about relations, project scope, and where links appear is shared with all other sources — this page covers what is unique to Linear.

Connecting Linear

Connecting Linear is a one-time, per-workspace action performed by an administrator in Admin → Integrations → Trackers. Linear is the first row of the Trackers list.

1. On the Linear row, click Connect. You are redirected to Linear to approve access.
2. Approve the request in Linear. You are returned to TestOrchestrator, a message confirms that Linear is connected, and the Linear settings dialog opens so you can choose a default project straight away.

The Linear row then reads Linear — your workspace, with where drafted cases land underneath and the projects it is available in beside it. Its status is one of:

• Connected — everything is set up.
• Needs a project — connected, but no default project is chosen yet, so “Generate tests” has nowhere to put the cases it drafts. A banner above the list offers Choose project.
• Disabled — still connected, but hidden from link pickers (see below).
• Reconnect — Linear no longer accepts the saved authorization. Click Reconnect to authorize again.
• Not connected — the row offers Connect.
• Can’t check — the connection status could not be loaded. Linear may still be connected, so Connect is not offered; choose Check again in the row's … menu.

Why OAuth instead of an API token? Authorizing through Linear means no personal API token is copied into TestOrchestrator. Access is tied to the authorization your workspace admin granted and can be revoked at any time by disconnecting.

Linear is one OAuth-managed tracker. Authorizing creates it for you, and its workspace and authentication belong to the connection — which is why Linear is not offered when you add a tracker by hand, and why it has no page in the tracker editor.

Linear settings

Click the Linear row (or choose Linear settings… in its … menu) to open the Linear settings dialog. It shows when Linear was connected and the access that was granted, and holds everything you can change about the connection:

• Default project — where cases land when someone uses “Generate tests” in a Linear issue's sidebar. The dialog will not save without one.
• Enabled — whether project members can link Linear issues. Turning it off keeps the connection and existing links.
• Available in — all projects, or only the projects you pick (pick at least one).
• Disconnect — see below.

You can also switch linking on and off with Enable/Disable in the row's … menu; that change has an Undo. Saving the settings dialog does not, because it changes the connection and the tracker together.

The access token renews on its own, so no expiry date is shown.

Disconnecting Linear

Choose Disconnect Linear… in the row's … menu (or Disconnect in the settings dialog) and confirm. Disconnecting revokes TestOrchestrator's access to your Linear workspace, and sidebar actions stop working until you reconnect. When the QA agent is on, the confirmation also says that it will stop posting to Linear and that actions awaiting approval can no longer run.

While Linear is disconnected, searching for or creating a Linear issue from a test case or test run shows “Linear is disconnected — reconnect it in Admin › Integrations” instead of search results. An administrator reconnects it with Connect on the Linear row.

Existing links are kept. Disconnecting does not delete issues you have already linked — those references remain in place. They will simply stop refreshing live details until Linear is reconnected.

Linking a Linear issue with live search

For most providers, linking an external item means typing its key by hand. For Linear sources, TestOrchestrator replaces the manual key field with a live issue search in the link dialog.

1. On a test case, run, or exploration, open the External References panel and choose Link item.
2. Select your Linear source. The external-key field becomes a search box.
3. Type at least two characters of an issue key or title. Matching Linear issues appear as you type, each showing the issue key, its current status, priority, assignee, and Linear project where available.
4. Pick an issue from the results, choose a relation, and save.

If a search returns more matches than can be shown, the list notes that results were trimmed — refine your query to narrow them down. Selecting an issue fills in its key, URL, and title automatically, so the saved link always points at a real issue.

AI insight on linked Linear issues

When you link a Linear issue, TestOrchestrator generates a short AI insight — a plain-language summary of what the issue is about — and displays it beneath the linked issue in the External References panel.

• While the insight is being generated, a subtle placeholder appears and updates on its own when the summary is ready — no page refresh needed.
• If the linked issue has no description or nothing meaningful to summarise, no insight is shown.
• Team members with permission to manage external references see a Regenerate button to recompute the insight — useful after the issue's description changes in Linear.

AI insight is an AI-assisted feature and is available on plans that include AI capabilities. The summary is meant as a quick reference inside TestOrchestrator — always confirm details against the issue in Linear.

Generating test cases from the Linear sidebar

Once Linear is connected and a default project is chosen, your team can trigger test-case generation directly from a Linear issue. Use the Generate tests action in a Linear issue's sidebar to draft test cases from that ticket. The generated cases are created in the default project you selected on the Linear connection card.

Tracking sidebar activity

TestOrchestrator surfaces a Linear sidebar activity card that lists the most recent sidebar-triggered generation runs for a project. Each entry shows the issue key, how many cases were generated (or whether the run is still in progress or failed), and when it finished. The card refreshes on its own while it is open, so you can watch a generation complete without reloading.

• Success — the run finished and created the listed number of test cases.
• Pending — generation is still running.
• Failed — generation could not complete; the entry shows the reason.

If you have not used the sidebar action yet, the card explains how to populate it: trigger Generate tests from a Linear issue's sidebar.

QA Agent: test results back to Linear

The QA Agent closes the loop in the other direction: instead of pulling work out of Linear, it sends test outcomes back. It runs after a test run is closed — which means somebody used Close run, the only act that closes one. Moving a run into a workflow state does not close it and does not wake the agent. It is not real-time, scheduled, or triggered by a button.

The QA Agent is off by default, requires a plan that includes AI capabilities (it is not available on the Free tier), and never closes a Linear issue or files a bug without an admin approving it first.

What it looks at

When a run closes, the agent only considers results that map to a linked Linear issue through your existing traceability links. Results that are not linked to a Linear issue are skipped. It works with Linear only — not Jira, Azure DevOps, GitHub, or Notion. For each linked issue it classifies the outcome (for example newly passing, a regression, still failing, or below half passing) and asks your tenant's admin-configured AI model to draft a short, developer-facing summary of how that issue's coverage did.

What it can do in Linear

From that analysis the agent plans actions and sorts them into two tiers:

• Low-risk actions — post the summary as a comment on the issue, move a regressed issue back to In Progress, and add your label for failures (needs-fix unless you change it) to an issue when fewer than half of its linked cases pass. These run automatically only when auto-actions are turned on for your tenant. When auto-actions are off, they are logged but suppressed — the summary comment is not posted.
• High-risk actions — move an issue to Done, or create a "Bug:" sub-issue. These are always approval-gated: they are queued for an admin to approve or reject, and only reach Linear once approved.

The agent does not reassign issues.

The activity log

Every decision the agent makes — auto-executed, queued for approval, suppressed, or skipped — is recorded in an append-only activity log that serves as the audit trail. The log is isolated to your tenant. The AI summary text itself is not stored; only a hash of it is kept.

Turning it on

The QA Agent is opt-in per tenant and has several gates, all of which must be satisfied for it to act:

• The QA Agent must be enabled for the tenant (off by default).
• Automatic low-risk actions require a separate auto-actions opt-in (also off by default); without it, high-risk actions still queue for approval but low-risk actions are suppressed.
• AI must be enabled and opted into for the tenant, on a plan that includes AI capabilities — the Free tier has no AI budget, so a paid plan (Starter or higher) is required.
• Enabling the agent or auto-actions, choosing the label for failures, and approving or rejecting queued actions, is done by admins on the QA agent tab of Admin → Integrations.

The QA agent tab

The QA agent tab of Admin → Integrations has three parts:

• The switches — Analyse closed runs turns the agent on; Run low-risk actions automatically turns on auto-actions (it needs the agent on). Each change applies immediately and can be undone from the message that confirms it. Label for failures picks the Linear label the agent adds (see below). Underneath, one sentence states what the agent will do with the current settings. When Linear is not connected, a banner says so and the switches are locked.
• Awaiting approval — the high-risk actions waiting for an admin, grouped by the run that proposed them. Each group is headed by the run's name (it opens the run), when it closed and its result, for example “31 passed · 1 failed”. Each proposal shows the action, the agent's one-line reason and the Linear issue; the issue key opens the issue in Linear in a new tab, and hovering or focusing it shows the issue's title and state (or Title not cached before TestOrchestrator has read it). Click a proposal to review it: the dialog shows the issue, its current state — for a state move, the change itself, such as In Review → Done — and exactly what will be written to Linear. Approve and run writes it to Linear immediately and cannot be undone from TestOrchestrator; Dismiss drops the proposal without writing anything.
• Activity — the decision log, newest first, each row timed like a test case’s Updated (just now, 2m ago, 3h ago, 2d ago; hover or focus the time for the exact date and time — the same goes for Waiting and a run’s closed time above), with an Outcome filter (Done, Failed, Awaiting approval, Skipped) and pages of 20. Hover or focus an action or its outcome for the agent's reasoning, and an issue key for the issue's title and state. The Outcome filter narrows the page you are looking at.

Issue titles and states on this tab are the ones the agent last read from Linear, so they can lag behind a change made in Linear since. The small Linear mark before each issue key says which tracker the issue lives in.

The label for failures

Label for failures is the Linear label Add label puts on a linked issue when fewer than half of its cases pass. It is needs-fix until you change it, and you pick it from the labels that exist in your Linear workspace (the list is searchable). Changing it applies immediately and can be undone from the confirmation message. The setting is locked, with the reason on hover, while the agent is off, while Linear is not connected, or when you do not have permission to manage integrations.

The agent applies a label; it never creates one. If the configured label does not exist in Linear, the setting says so — the label is listed first in the picker marked Not in Linear — and every Add label is skipped until you create the label in Linear or pick one that exists. The Activity log records each skip with the reason (hover the Skipped outcome).

TestOrchestrator reads your Linear labels at most once every five minutes, so a label you have just created in Linear can take up to five minutes to appear in the picker.

Who can do what

Related