# Linear (issue sync)

Connect a Linear team to Usero and issues sync both ways with your inbox. Issues become feedback, feedback becomes issues, and
marking an issue Done resolves its feedback. It is the same Issue sync as the GitHub integration, pointed at Linear.

Connection is Linear OAuth: you approve the Usero app once for your workspace, then pick the team to sync with.

## What it does

- **Issues become feedback.** Existing and new issues in the chosen team land in your inbox, next to widget, email, and Slack
  feedback, and feed the same clustering and analysis. Closed issues are never imported.
- **Feedback becomes issues.** **Create issue** on any feedback item opens one in the team. The issue links back to the feedback.
- **Status follows.** Moving an issue to a Done or Cancelled state resolves its feedback. Resolving feedback moves its issue to
  the team's first Done state. Reopening either side reopens the other.

## Prerequisites

- A Usero account. Anonymous visitors can browse but cannot connect Linear; the button prompts you to sign up first.
- A Linear workspace where you can authorise apps.

## Connect Linear

1. Open your project, then go to **Integrations** (the URL is `usero.io/YOUR_CLIENT_ID/integrations`). To open your own
   integrations page, [go here](/integrations).
2. Find the **Linear** card and click **Connect Linear**.
3. Approve the Usero app on Linear's authorisation screen. Linear sends you back to the Linear card, now open and marked
   **Connected**.

## Choose the team

Issue sync works with one Linear team per project.

1. On the Linear card, the **Team** row shows the chosen team, or **Not chosen yet**.
2. Click **Change**, then pick the team from the list.
3. The first time a team is chosen, issue sync switches on in both directions and Usero imports the team's open issues straight
   away. The card shows **Importing issues** while that runs; you can leave the page.

## Issue sync

The card reads as one sentence: **Sync [both ways] between Linear and Usero.** The dropdown has four options:

- **Both ways** (the default after choosing a team): issues become feedback and feedback becomes issues.
- **Linear to Usero only**: issues become feedback; the Create issue button is off.
- **Usero to Linear only**: Create issue works; nothing is imported.
- **Off**: no sync in either direction. Feedback already imported stays in your inbox.

Under the sentence, two lines say what each half does. **Linear to Usero: issues with these labels land in your inbox.** The
**Labels** row lists the label filter; click **+** to add a label from the team, or leave it empty to import every open issue. The
status line reads **N synced, 12 minutes ago**, with **Re-sync** to re-import issues that match your labels. Existing feedback is
never duplicated.

**Usero to Linear: create issues manually.** By default an issue is only created when someone clicks **Create issue** on a
feedback item. Switch the dropdown to **automatically for every new feedback item** or **automatically for bugs only** if you want
Usero to open the issue for you.

**Recent** lists the last three sync events (an issue imported, an issue created, an issue marked Done, a backfill) with the
direction in words.

Only one tracker can hold **Usero to X** at a time. If GitHub has it and you switch it on for Linear, the GitHub card changes to
**GitHub to Usero only** and shows **Create issue now goes to Linear.**

## Create an issue from feedback

1. Open any feedback item in the inbox.
2. Click **Create issue**. The title and description are pre-filled from the feedback; edit them and add labels if you like.
3. The issue opens in your Linear team, and the feedback item shows a chip such as **ENG-12 · Open**. When the issue is marked
   Done, the chip reads **ENG-12 · Closed** and the feedback is resolved.

## Troubleshooting

**The Linear card says "Not configured in this environment."** Linear OAuth credentials are not set on this deployment. On
usero.io they are; on a self-hosted or preview deployment, add `LINEAR_CLIENT_ID`, `LINEAR_CLIENT_SECRET` and
`LINEAR_WEBHOOK_SECRET`.

**The card says "Needs attention".** The last import failed, usually because the Linear token was revoked. The line under the
sentence names the cause; click **Reconnect Linear** to authorise again.

**Nothing is imported.** Check the **Labels** row: with a filter set, only issues carrying one of those labels are imported.
Closed issues are never imported. Click **Re-sync** after changing the filter.

**Create issue is disabled.** The sentence on the Linear card must include **Usero to Linear** (either **Both ways** or **Usero to
Linear only**), and a team must be chosen. If GitHub holds **Usero to GitHub**, switching Linear on takes it over.

**An issue closed in Linear did not resolve its feedback.** Status follows for issues imported by Usero and for issues created
from feedback. An issue linked by hand in Linear is not tracked. Check the **Recent** list on the card for the last events.

## Next

- [GitHub integration](/docs/integrations/github)
- [Integrations overview](/docs/integrations)
- [Find your clientId](/docs/find-your-client-id)