> 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.

Webhooks need no setup on your side. Nullify's Linear app carries its own `Issue` and `Comment` webhook subscription, and Linear starts delivering your workspace's events to Nullify the moment you approve the consent screen. Nothing is created in, or requires admin rights on, your workspace. 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 an access token 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.

### Assignee

New Linear tickets require an active assignee in the destination team. Set a default assignee in the Linear integration settings, or confirm a security owner in Ticketing settings. Existing tenants need to complete this setup before automatic ticket creation can succeed.

API: include the Linear user's ID as `defaultAssigneeId` alongside `teamId` in `POST /admin/integrations/linear/ticket-config`. Nullify validates the account before saving it. Omit the field to preserve the current default; send an empty string to clear it.

Changing teams while omitting `defaultAssigneeId` preserves the saved account. Ticket creation revalidates that account against the destination team. If it cannot be assigned there, Nullify tries the confirmed security owner; without an eligible account, creation requires an explicit assignee. Send a new default or clear the old one when changing teams if this is not desired.

An explicit selection takes precedence over the default, followed by the confirmed security owner. If no account is available, automatic creation stops and manual creation returns a precondition error and asks you to choose an assignee. The recommended owner in the ticket body does not change assignment. See [Assignee rules](/connectors/jira/assignee.md).

### 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. The `Issue` and `Comment` subscription lives on the Nullify Linear app itself, so authorizing the app is the only step — 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 Nullify app's signing secret before anything in the payload is read. Deliveries whose signature does not match are rejected — Nullify never processes an unverified state change. Deliveries are also de-duplicated so a Linear retry of the same event is not applied twice.

{% hint style="info" %}
Every authorizing workspace's events arrive on one Nullify endpoint. Nullify reads your workspace's organization ID from the verified payload and resolves it to your tenant from the OAuth install record, so events are only ever applied to your own findings. No additional setup is required on your side.
{% endhint %}