# Linear integration

Authorize Linear, choose a team, and turn feedback into Linear issues automatically or one thread at a time.

Source: https://docs.annot8.app/docs/integrations/linear



**Pro and above.** A workspace admin authorizes Linear once and picks the team
that issues go to. There's no API key to create or paste.

## Connect [#connect]

<Steps>
  <Step>
    ### Start from Integrations [#start-from-integrations]

    **Integrations** in the sidebar → **Linear** → **Continue with Linear**.
  </Step>

  <Step>
    ### Authorize Annot8 in Linear [#authorize-annot8-in-linear]

    Linear asks you to approve access for Annot8, then sends you straight back to
    the dashboard. The connection is tied to the admin who authorized it.
  </Step>

  <Step>
    ### Choose a team [#choose-a-team]

    Annot8 lists the Linear teams your account can see. Pick the one new issues
    should land in and **Save**. If there's only one team, it's selected for you.
  </Step>

  <Step>
    ### Test it [#test-it]

    Annot8 runs a test as soon as you save. The integration row then shows
    **Working** or the error Linear returned. Use **Test** at any time to check
    again.
  </Step>
</Steps>

Once saved, the connection applies to **every project** in the workspace. To
keep a project out of Linear, switch it off under **Project → Integrations**.

<Callout type="info">
  Connected Linear with a personal API key before guided setup arrived? The
  integration row shows **Reconnect needed**. Choose **Reconnect** and authorize
  Linear. The existing connection is updated in place, so there's no need to
  disconnect first.
</Callout>

## Two ways issues get created [#two-ways-issues-get-created]

**Automatically**, for every new thread on a project where Linear is on. The
issue is titled `Feedback: <comment>` and carries the author, the comment, and a
link to the page.

**On demand**, from a single thread: right-click it in the inbox and choose
**Create issue → Create Linear issue**, or use **Links** in the thread's detail
panel. This issue is richer. It carries the project, page path and full URL,
issue type, priority, status, expected and actual behaviour, the element
selector, and the page title.

<Callout type="warn">
  If your Linear team is an active sprint board rather than a triage inbox,
  switch Linear **off** for the project and create issues on demand. Otherwise
  every piece of feedback becomes a Linear issue.
</Callout>

## Permissions [#permissions]

The grant belongs to the admin who authorized it, so issues are created with
that person's Linear access. If they leave the workspace, lose access to the
team, or revoke Annot8 in Linear, the row shows **Reconnect needed**. Another
admin can choose **Reconnect** and authorize with their own account.

To switch accounts at any time, open **Configure** and choose **Use a different
Linear account**.

## Different teams per project [#different-teams-per-project]

Under **Project → Integrations**, choose **Route…** next to Linear, pick a
different team for that project, and **Save route**. **Use workspace default**
removes the route again.

## Troubleshooting [#troubleshooting]

**No teams listed.** The authorizing account can't see any Linear teams. Choose
**Update access**, or authorize with an account that belongs to the team.

**Nothing is created.** Check the integration row's status. The usual causes
are a revoked authorization, or an authorizing admin who has since lost access
to the team. Reconnect to fix either.

**Issues land in the wrong team.** The selected team decides the destination.
Change it with **Configure**, or set a per-project route.