Linear

Pro and above. Setup is an API key plus a team id.

Linear has no incoming webhook. If you configured Linear before this changed and stored a webhook URL, that configuration cannot deliver and will show as an error — reconnect with an API key and team id.

Connect

Create a personal API key

In Linear: Settings → API → Personal API keys → Create key. Name it "Annot8" and copy the value — it starts with lin_api_ and is shown once.

Find your team id

The team id is a UUID. Query the Linear API for it:

query {
  viewer {
    teams {
      nodes {
        id
        name
      }
    }
  }
}

Or take it from your internal setup notes.

Connect in Annot8

Integrations in the sidebar → Linear → paste the API key and team id → Connect, then Test.

Enable it per project

Project → Integrations → toggle Linear on.

Two ways issues get created

Automatically, for every new thread on a project where Linear is enabled.

On demand, by right-clicking a thread in the inbox and choosing Integrations → Create Linear issue.

The on-demand issue is richer: it carries the thread title, project, page path and full URL, issue type, priority, status, expected and actual behaviour, and the element selector. The automatic one carries the comment, the author, and the page link.

If your Linear team is an active sprint board rather than a triage inbox, leave the integration off for the project and create issues on demand. Otherwise every piece of feedback becomes a Linear issue.

Permissions

A personal API key acts as you. Issues created by Annot8 will show your account as the creator, and the key inherits your access. For a team setup, create the key on a service account rather than a person who might leave.

Troubleshooting

Nothing is created. Check the last-delivery status. The usual causes are a revoked API key, a team id from a different workspace, or a key created by someone who's lost access to that team.

Issues land in the wrong team. The team id decides the destination. Set a per-project override with a different team id under Project → Integrations.

Linear

On this page