---
title: Linear Integration
description: Connect Linear and keep Landed Issue execution status aligned across systems.
---

This guide helps an **Admin** connect and configure Linear for one workspace.

## Quick Actions

  }
  >
    Share the SEO landing page with prospective workspace admins.
  
  }
  >
    Diagnose OAuth, webhook, mapping, and backfill issues.
  
  }>
    Return to the integrations overview.
  

## What the Linear Integration Does

- Links Landed Issues to Linear issues.
- Keeps status changes synchronized in both directions.
- Applies default assignee, project, labels, and priority for synced Linear issues.
- Supports backfilling open Landed Issues into Linear in chunks.

## Prerequisites

- Admin access in the Landed workspace.
- A Linear account with access to the target organization.
- Linear admin-level permission to create webhooks during setup.

Required OAuth scopes shown in product setup:

- Read access to the Linear workspace.
- Write access to the Linear workspace.
- Admin access to manage settings and people (required for webhook creation).

## Connect Linear

1. Open **Integrations** in your workspace dashboard.
2. Select **Linear**.
3. Click **Connect Linear**.
4. Complete the Linear OAuth flow and accept required scopes.
5. Confirm the connection badge shows **Connected**.

If setup completes authentication but webhook setup fails, reconnect with a Linear admin account.

## Configure the Integration

### 1. Connection

- Enable or disable sync for this connection.
- Mark the connection as default for automated Linear actions.
- Select a default Linear team for routing and catalog sync.
- Save with **Save connection**.

### 2. Status Mapping

- Use one row per Linear state.
- Map each Linear state to a Landed status.
- Set fallback mappings for each status type:
  - **Fallback from Landed**: used when a Landed type has no direct Linear state.
  - **Fallback from Linear**: used when a Linear type has no direct Landed status.
- Click **Sync statuses from Linear** to refresh state catalog after changes in Linear.
- Save with **Save mappings**.

### 3. Issue Defaults

Choose what is included in issue descriptions:

- Summary
- Original Issue content
- Representative user quotes
- Issue link back to Landed

Set default values for new/updated Linear issues:

- Default assignee
- Default project
- Default priority
- Default labels

Save with **Save defaults**.

### 4. Backfill and Diagnostics

- Run **Start backfill** to link open existing Landed Issues to Linear in chunks of 20.
- Stop a running backfill if needed.
- Track processed, created, linked, skipped, and failed counts.
- Use technical fields (connection ID, organization, default team) for debugging.

## Expected Result

- New Landed Issues can sync to Linear.
- Status changes remain aligned in both tools.
- Backfill links legacy open Issues without manual recreation.

## Ongoing Workflow

1. Triage feedback in Landed as usual.
2. Link Landed Issues to Linear where execution should happen.
3. Monitor status alignment in both systems.
4. Re-sync status catalog if your team changes workflow states in Linear.

## Need Help?

Use [Linear Troubleshooting](/docs/integrations/linear/troubleshooting) for common setup and sync failures.