> ## Documentation Index
> Fetch the complete documentation index at: https://docs.app.strix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear Integration

> Connect Strix to Linear to export vulnerabilities as issues and keep statuses in sync

export const ScarfPixel = () => <img referrerPolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=831669b6-b4bd-42cb-8832-2122c03e1d5f" alt="" width="1" height="1" style={{
  position: "absolute",
  width: 0,
  height: 0,
  opacity: 0,
  pointerEvents: "none"
}} />;

<ScarfPixel />

Strix connects natively to Linear. Strix can export the vulnerabilities that pentests and PR reviews find as Linear issues, and keep the statuses synchronized in both directions. This page describes the setup, the OAuth scopes that Strix requests, the data that Strix and Linear exchange, and the disconnect procedure.

## Overview

| | |
| - | - |
| Integration type | Native Linear OAuth 2.0 app — no third-party middleware in the data path |
| Direction | Bidirectional. Strix creates and updates issues. Linear status changes come back through a webhook |
| Who can connect | Strix organization **admins** only |
| Scope of access | The Linear workspace that the authorizing user approves |

## Setup

1. In Strix, go to **Settings → Integrations** and click **Connect** on the Linear card. You must be an organization admin, and your plan must include ticketing integrations.
2. Approve the app on the standard Linear consent screen (`linear.app/oauth/authorize`). Linear redirects back to `https://app.strix.ai/api/integrations/linear/callback`. There, Strix exchanges the authorization code for a token and records the workspace.
3. In Strix, select a **default team or project** as the export destination. The picker lists your Linear teams first, then your projects. Select a team to create tickets in that team; select a project to create tickets in that project. You can also enable **auto-sync** with a minimum severity. Auto-sync exports new findings automatically.
4. Optional: route findings to other teams or projects. Under **Route by source**, select a destination for pentests, PR reviews, or supply-chain findings. Under **Route by repository**, select a destination for findings from one repository. Both cards sit under **Advanced** on the settings page and are collapsed by default. See [Route tickets](#route-tickets).

## Route tickets

Strix can send findings to different Linear teams or projects. Linear and Jira share the same routing model. Strix resolves the destination of each ticket in this order:

1. The destination that you select in the export dialog.
2. The repository route of the repository that the finding belongs to.
3. The source route of the finding source.
4. The default team or project.

Manual exports, bulk exports, the API, and auto-sync all use the same order.

### Route by source

Open **Settings → Integrations**, click **Configure** on the Linear card to open its settings page, and expand **Route by source** under **Advanced**. The card shows one destination for each source:

| Source | Findings |
| - | - |
| Pentests | Findings from pentests (API key `scan`) |
| PR reviews | Findings from pull request reviews |
| Supply chain | Dependency vulnerabilities (`finding_class` is `dependency_cve`) |

If a source has no destination, Strix uses the default team or project.

### Route by repository

Click **Add repository route…** and select a repository. Then select the team or project for its findings. Strix matches a pentest finding through the repositories of the pentest and a PR review finding through the repository of the pull request. A repository route has priority over a source route.

### Set routes through the API

The `source_routes` object replaces the stored source routes. To use the default destination for a source, set the key to `null` or leave the key out. The `repository_routes` array replaces the stored repository routes. A repository that is not in the array loses its route.

```bash theme={null}
curl -X PATCH "https://app.strix.ai/api/v1/integrations/linear/settings" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_routes": {
      "pr_review": { "collection_id": "<LINEAR_TEAM_OR_PROJECT_ID>", "collection_name": "AppSec" },
      "supply_chain": { "collection_id": "<LINEAR_TEAM_OR_PROJECT_ID>", "collection_name": "Dependencies" }
    },
    "repository_routes": [
      { "repository_id": "<REPOSITORY_ID>", "collection_id": "<LINEAR_TEAM_OR_PROJECT_ID>", "collection_name": "Payments" }
    ]
  }'
```

`GET /api/v1/integrations/linear/settings` returns the stored routes and, for administrators, the connected repositories with their identifiers.

**Required scope:** `integrations:write`

## Ticket defaults

The Linear settings page (**Settings → Integrations → Configure**) holds the defaults that Strix applies to every ticket that it creates. Manual exports, bulk exports, the API, and auto-sync use the same defaults.

### Default assignee

Select a Linear user in **Default assignee**. Strix lists the active users of the connected workspace. Strix assigns every new ticket to that user. Leave the field empty to create unassigned tickets.

### Title and description templates

Strix renders the ticket title and description from templates. A template mixes text with placeholders in double braces. The default title template is `{{title}}` and the default description template is `{{details}}`.

| Placeholder | Value |
| - | - |
| `{{title}}` | The finding title |
| `{{severity}}` | The severity, for example `high` |
| `{{cve}}` | The CVE identifier of a dependency finding, or empty |
| `{{cvss}}` | The CVSS score, or empty |
| `{{target}}` | The target of the pentest |
| `{{endpoint}}` | The affected endpoint or file |
| `{{repository}}` | The repository of the finding |
| `{{pentest}}` | The name of the pentest |
| `{{source}}` | `Pentests`, `PR reviews`, or `Supply chain` |
| `{{strix_url}}` | The link to the finding in Strix |
| `{{details}}` | The full finding description that Strix writes today |

Strix rejects a template that contains an unknown placeholder. A title template can hold 500 characters and a description template 20,000 characters.

### Group tickets by pentest

Turn on **Group tickets by pentest** to collect the tickets of one pentest in one Linear project under the selected team. Select a **team** as the default destination for this to apply. Strix creates the project the first time that it exports a finding from the pentest and reuses it afterwards. Tickets from PR reviews and supply chain findings are not grouped. If the destination is a Linear project (a route or the default points at a project, not a team), Strix keeps the tickets in that project and does not create a pentest project.

### Preview and test ticket

Click **Preview ticket** to see the rendered title, description, destination, and assignee of a sample finding. Click **Send test ticket** to create a real ticket in the default team or project from the same sample. **Send test ticket** requires the administrator role.

### Set defaults through the API

```bash theme={null}
curl -X PATCH "https://app.strix.ai/api/v1/integrations/linear/settings" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "default_assignee_id": "<LINEAR_USER_ID>",
    "title_template": "[{{severity}}] {{title}}",
    "description_template": "{{details}}\n\nStrix: {{strix_url}}",
    "group_by_pentest": true
  }'
```

Set `default_assignee_id` to `null` to remove the assignee and a template to `null` to restore the default. Strix validates the assignee against the users that `GET /api/v1/integrations/linear/users` returns.

| Method | Path | Purpose | Scope |
| - | - | - | - |
| `GET` | `/api/v1/integrations/linear/users` | List the users that Strix can assign | `integrations:read` |
| `GET` | `/api/v1/integrations/linear/preview` | Preview a sample ticket with the stored defaults | `integrations:read` |
| `GET` | `/api/v1/vulnerabilities/{vulnerabilityId}/preview` | Preview the ticket for one finding | `integrations:read` |

The finding preview has a `mode` field. `create` shows the ticket that a push opens, with its `destination`. `update` means that the finding already has a ticket: a push only updates its description and status, so `existing_ticket` gives the link to it and `destination` and `ticket.title` are `null`.
\| `POST` | `/api/v1/integrations/linear/test-ticket` | Create a test ticket in the default team or project | `integrations:write` |

## OAuth scopes requested

| Scope | Why Strix needs it |
| - | - |
| `read` | List teams and projects, and read issue status during synchronization |
| `write` | Create issues, post status comments, and update issue state |

Linear supplies long-lived access tokens (no refresh token). Thus the connection continues until you disconnect it or revoke it.

## What data flows where

**Strix → Linear** (when you export a vulnerability manually, or when auto-sync exports it):

* Issue title: the vulnerability title.
* Issue description: severity, CVSS and CVE (when present), target, endpoint or affected file, impact, technical analysis, evidence, suggested fix or remediation steps, proof of concept, and a link back to the issue in Strix.
* Priority mapped from severity, and a due date when an issue is snoozed.
* Status comments (for example, "marked In Progress by …") when the Strix status changes.

**Linear → Strix** (through a webhook on issue updates):

* The issue ID and identifier, its workflow state type (for example, started or completed), and the display name of the actor who made the change. Strix applies the state to the status of the linked vulnerability.

Strix does not read existing Linear issues, comments, or user directories. Inbound processing applies only to status updates for the issues that Strix created.

## Security

* **Admin-gated**: The connect and callback endpoints require an authenticated Strix org admin. Strix checks the role again at the callback. Thus a demoted user cannot complete a pending connection.
* **CSRF-protected OAuth**: The OAuth `state` is HMAC-signed and bound to the initiating organization and user. It expires after 10 minutes.
* **Signed webhooks**: Strix makes sure that each Linear webhook delivery has a correct HMAC-SHA256 signature (in a timing-safe comparison) and a timestamp in the permitted window. This limits replay.
* **Token storage**: Strix keeps the access token server-side in its database. The token applies only to your organization. The browser and other tenants cannot see it.
* **Revocation on disconnect**: When you disconnect the integration, Strix revokes the token on the Linear side. Thus no live tokens stay.
* **Audit trail**: The Strix audit log records the connection of the integration and the changes to the settings.

## Disconnecting

An org admin can disconnect Linear at any time from **Settings → Integrations**, or through the API:

```bash theme={null}
curl -X DELETE "https://app.strix.ai/api/v1/integrations/linear" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

**Required scope:** `integrations:write`

The disconnect operation removes the stored token and revokes the OAuth grant. Strix does not delete the issues that it already created in Linear.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.