> For the complete documentation index, see [llms.txt](https://docs.nullify.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nullify.ai/connectors/linear.md).

# Linear

## Overview

Nullify can be configured to integrate with Linear to automatically create and update issues based on the findings in your project. It is Nullify's second ticketing provider after [Jira](/connectors/jira.md).

When a finding crosses the configured threshold, Nullify files a Linear issue in your chosen team. As work progresses, Nullify keeps the issue in sync — and as your team moves the issue through its workflow in Linear, those status changes flow back into Nullify so the finding's ticket state stays accurate on both sides.

Nullify posts updates asynchronously so developers stay inside their existing workflows.

## Installation

Nullify connects to Linear over OAuth 2.0 using a Nullify-owned Linear app — there is nothing to install from the Linear marketplace and no app descriptor to upload.

### Connect your Linear workspace

1. In the Nullify dashboard, go to **Configure -> Integrations** and start the Linear connection. A user with config-write permission must perform this step.
2. Nullify generates a Linear authorize URL and redirects your browser to Linear's consent screen. The app requests the `read` and `write` scopes so it can create issues, update their status, and read the issues it manages.
3. Approve the consent screen in Linear. Linear redirects your browser back to Nullify, which exchanges the authorization code for an access token and records the install against your tenant. You'll see a "Linear connected" confirmation page.

During the callback, Nullify also registers its webhook on your Linear workspace automatically (for `Issue` and `Comment` events) and stores the per-install signing secret encrypted at rest — there is no manual webhook to create. See [Webhook Sync](#webhook-sync) below.

{% hint style="info" %}
You can check whether your tenant has completed the Linear install at any time — the dashboard reflects the connection status, backed by `GET /admin/integrations/linear/oauth`.
{% endhint %}

### API reference

The OAuth flow is driven by the admin API:

* `GET /admin/integrations/linear/install` — starts the install. Returns the Linear authorize URL the browser is sent to, and persists a short-lived state token keyed to your tenant.
* `GET /admin/integrations/linear/oauth/callback` — the redirect target Linear returns to. Exchanges the code for a token, registers the webhook, and records the install.
* `GET /admin/integrations/linear/oauth` — returns whether your tenant has a completed Linear install on record.

## What it does

Once connected, Nullify creates a Linear issue for each finding above the configured threshold and updates it over the finding's lifecycle:

* **Create** — a new finding produces a new Linear issue in your configured team.
* **Status sync** — when the finding is fixed, Nullify moves the issue toward a completed state; when the issue is reopened or moved back in Linear, that reopen is reflected on the Nullify side.

Linear issues are created with the **Task** issue type by default, consistent with the rest of Nullify's ticketing.

## Configuration

The Linear connector is configured from the Nullify dashboard under **Configure -> Ticketing** (and the per-integration Linear settings) — there is no `.nullify.yml` file.

### Team

Nullify files work items against a specific Linear **team**. Set the team in the Linear integration settings; this is what tells manual and automatic ticket creation which Linear team an issue should be created in. Until a team is set, the Linear integration stays inactive even if the OAuth install has completed — the team association is the trigger that turns ticketing on.

API: `POST /admin/integrations/linear/ticket-config` with the target `teamId`. This is stored independently of the OAuth tokens, so you can connect the workspace and choose the team in either order.

### Severity and Priority Threshold

By default, Nullify creates tickets using the same severity and priority thresholds reported in the dashboard. You can also set thresholds specific to ticket creation under **Configure -> Ticketing**, per finding type.

For example, you might want the issues dashboard to include all findings of priority IMPORTANT or higher, but only create a Linear issue for findings that are URGENT. Nullify's priority taxonomy is `URGENT`, `IMPORTANT`, `MEDIUM`, and `LOW`, so you can surface everything at IMPORTANT or higher on the dashboard while only ticketing URGENT findings.

### Disable

You can disable automatic Linear ticket creation from the dashboard. A typical use case is when you have the Linear connector configured globally but want to turn off automatic ticket creation for a specific repository — for example, an internal tool or script that is not used in production.

You can also disable *automatic* ticket creation while keeping the team configured, so that you can still *manually* create tickets from the dashboard when needed.

## Webhook Sync

Status changes you make in Linear are synced back into Nullify automatically through the webhook that Nullify registered during install. The webhook is registered for `Issue` and `Comment` events; Nullify processes the changes that matter for keeping finding tickets accurate:

* **Workflow-state changes** — when an issue moves to a new workflow state, Nullify maps Linear's state type (for example a `completed` or `cancelled` state) to the corresponding internal ticket status and updates the finding's ticket. A move into a terminal state is treated as a close; a move back out is treated as a reopen. Tenants running a custom Linear workflow can override the default state mapping per tenant.
* **Assignee changes** — assignee updates on a tracked issue are forwarded so the finding's ticket reflects who currently owns it.

Edits that don't affect workflow state or assignee (label-only changes, comment-only events, title edits) are ignored.

Each delivery is verified with an HMAC-SHA256 signature against the per-install signing secret captured at install time. Deliveries whose signature does not match are rejected — Nullify never processes an unverified state change for a workspace with a configured secret. Deliveries are also de-duplicated so a Linear retry of the same event is not applied twice.

{% hint style="info" %}
Linear routes the inbound events to Nullify by your workspace's organization ID, which Nullify resolves to your tenant from the OAuth install record. No additional setup is required on your side.
{% endhint %}