> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pensar.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pensar.dev/_mcp/server.

# Linear

> Connect Linear to sync Pensar findings as issues and auto-resolve them

# Linear Integration

Pensar Console integrates with Linear to push security findings into your Linear workspace as issues and keep their status in sync. The integration uses a **workspace-level OAuth 2.0 app** — you authorize Pensar once, and there are no personal API keys to create or rotate.

> **Note**
>
> Linear issues created by Pensar are attributed to the **Pensar app**, not to the person who connected the integration. The connection is approved by a Linear admin during the OAuth consent and is shared by everyone in your Pensar workspace.

## Prerequisites

Before connecting Linear, ensure you have:

1. **A Linear workspace** where you can approve installing an OAuth application (this requires a Linear admin)
2. **Admin or owner access** to the Pensar Console workspace you want to connect

## Connecting Linear

1. Navigate to **Settings** → **Integrations** → **Issue tracking** in your Pensar Console workspace
2. Find the **Issue sync** card and locate the **Linear** section
3. Click **Connect Linear**
4. You'll be redirected to Linear's OAuth consent screen — a Linear admin reviews the requested access and approves the app for your workspace
5. You'll be automatically redirected back to Pensar Console with Linear connected

Once connected, the Linear section shows the connected organization.

### Permissions

When you authorize Pensar, the OAuth flow requests the following scopes:

| Scope               | Purpose                                               |
| ------------------- | ----------------------------------------------------- |
| **read**            | Read teams and issues to route and reconcile findings |
| **issues:create**   | Create Linear issues for security findings            |
| **comments:create** | Add comments to synced issues                         |

## What Gets Synced

Once connected and enabled, Pensar files each matching finding as a Linear issue in the routed team:

* The issue **title** is prefixed with `[Pensar Security]`
* The **description** includes the severity, affected location, CWE classification, and a direct link back to the finding in the Pensar Console
* The issue is tagged with Linear labels matching GitHub Issues sync: `security`, `pensar`, and `severity:<level>` (created on the team if they do not already exist)
* When configured, the issue is added to the selected Linear **project**
* The finding's **severity** maps to a Linear **priority**:

| Pensar severity | Linear priority |
| --------------- | --------------- |
| Critical        | Urgent          |
| High            | High            |
| Medium          | Medium          |
| Low             | Low             |

Issues are created as the **Pensar app**, so they're clearly attributable and don't consume a Linear seat.

### Opening a finding in Linear

When a Linear issue already exists for a finding, the finding's actions menu includes **View in Linear**. You can also file one from the same menu with **Open as Linear issue**. That per-finding create does **not** require auto-sync to be enabled — only that Linear is connected and a team is selected (the workspace default, or a per-repository override). If a Linear issue is already linked, Pensar opens that URL instead of creating a duplicate.

## Routing Findings to Teams

Pensar routes findings to Linear teams with a workspace default plus optional per-repository overrides.

### Default Team

1. In the **Linear** section, set the **Default team**
2. Optionally select a **Project** for that team
3. This destination is the fallback for any repository without an override, and for findings that aren't tied to a specific repository

### Per-Repository Overrides

Each repository can override the default routing:

| Setting             | Description                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------- |
| **Sync to Linear**  | Toggle whether findings from this repository are filed as Linear issues                     |
| **Team**            | The Linear team findings from this repository are filed in (falls back to the default team) |
| **Project**         | Optionally add created issues to a project available to the selected team                   |
| **Severity Filter** | The minimum severity required before a finding is filed as an issue                         |

> **Note**
>
> Select a team before enabling sync for a repository. Repositories without an override inherit the workspace default.

## Backfilling Existing Findings

Turning on sync only affects findings discovered from that point on. To file findings you already have, use **Sync existing findings** in the **Issue sync** card. Pensar files every open finding that meets the routing and severity rules, skipping any that already has a linked Linear issue.

## Two-Way Status Sync

### Pensar to Linear

When a finding's status changes in Pensar, the linked issue is moved to a workflow state of the matching type. This happens wherever the change is made: the console, the REST API, the CLI, MCP, a retest, or a merged pull request. A change that came from Linear itself is not sent back to it.

| Pensar status         | Linear state type |
| --------------------- | ----------------- |
| Open                  | Unstarted         |
| In review             | Started           |
| Closed                | Completed         |
| Closed as a duplicate | Duplicate         |
| False positive        | Canceled          |

When a finding is closed as a duplicate and its original has a Linear issue, Pensar marks the finding's Linear issue a duplicate of the original's and moves it to the team's duplicate state. If the original has no Linear issue, the finding's Linear issue is left as it is, so Linear keeps a record of the vulnerability. Reopening a duplicate, or closing it for another reason, removes the duplicate link in Linear.

### Linear to Pensar

Status changes made in Linear flow back automatically through Linear's app-level webhook. Pensar's Linear app is configured with a single webhook that Linear sends for every workspace that authorized the app, so there is no per-workspace setup and no extra scope required:

| Linear state type | Pensar status         |
| ----------------- | --------------------- |
| Backlog           | Open                  |
| Unstarted         | Open                  |
| Started           | In review             |
| Completed         | Closed                |
| Duplicate         | Closed as a duplicate |
| Canceled          | False positive        |

Moving an issue to a **canceled** state marks the finding a **false positive** rather than closing it as fixed. Moving a completed issue back to an active state reopens the finding.

Marking an issue a **duplicate** in Linear closes the finding as a duplicate of the finding whose Linear issue it duplicates. If that Linear issue has no finding in the same Pensar workspace, the finding is left unchanged. Moving that issue from Duplicate to Done re-closes the finding as resolved and drops the duplicate link. A finding already closed as wont-fix, out-of-scope, risk-accepted, or other stays on that verdict when its Linear issue is Done — Linear has no distinct states for those.

> **Note**
>
> Inbound reflection can be turned off per provider with **Reflect status changes from Linear**, in the **Linear** section. With it off, Pensar remains the source of truth: findings still sync outward to Linear, but changes made in Linear are ignored.

## Disconnecting Linear

To remove the Linear integration:

1. Navigate to **Settings** → **Integrations** → **Issue tracking**
2. Find the **Linear** section in the **Issue sync** card
3. Click **Disconnect**

Disconnecting revokes Pensar's access token for your Linear workspace.

> **Warning**
>
> Disconnecting Linear stops Pensar from filing new findings as Linear issues and ends two-way status sync. Existing Linear issues are left in place.

## Troubleshooting

### Connection Failed

If the OAuth authorization fails:

1. Ensure you're signed in to the correct Linear workspace
2. Confirm a Linear admin approved the app during consent
3. Verify you have admin or owner access to the Pensar Console workspace
4. Try the **Connect Linear** flow again from **Settings** → **Integrations** → **Issue tracking**

### Issues Not Being Created

If findings aren't appearing in Linear:

1. Confirm a **Default team** is set, or that the repository has a team override
2. Check that **Sync to Linear** is enabled for the repository
3. Verify the finding's severity meets the repository's **Severity Filter**
4. Open the finding and use **Open as Linear issue** from the actions menu — that files the ticket even when auto-sync is off, as long as a team is selected

### Status Changes Not Syncing

If moving a Linear issue to done doesn't resolve the Pensar finding:

1. Confirm the issue was originally filed by Pensar — status sync only applies to synced findings
2. Check that **Reflect status changes from Linear** is enabled
3. Confirm the state you moved to is of type **completed**, not a custom active state

## Need Help?

If you encounter issues setting up your Linear integration, please contact our support team at [team@pensar.dev](mailto:team@pensar.dev).