# Linear

> Connect Linear so MergeHarbor reviews each pull request against the Linear issue it implements and flags requirements the change misses.

When a pull request is linked to a Linear issue, MergeHarbor reads the issue and checks the change against its acceptance criteria.

## What it does in reviews

- **Finds linked issues.** MergeHarbor looks for issue identifiers such as `ENG-123`, or issue URLs such as `https://linear.app/acme/issue/ENG-123`, in the branch name, the pull request title, its description and its commit messages, in that order. Branch names match in any case (`feature/eng-123-rate-limit`, the format Linear suggests). It also asks Linear which issues have the pull request attached. Up to three issues are used per pull request. Strings such as `UTF-8`, `SHA-256`, `ISO-8601`, `RFC-…` and `CVE-…` are ignored.
- **Adds a requirements check to the review summary.** Acceptance criteria come from an "Acceptance criteria" or "Definition of done" section, a checklist, or Given/When/Then scenarios in the issue. Each criterion is marked **Met**, **Not met** or **Unclear**, with `file:line` evidence. If the issue has no criteria, MergeHarbor lists up to three requirements it inferred from the description, labelled "(inferred)". Under each issue, **Docs read** lists the Notion pages the review read for it.
- **Costs no extra model call.** The check is part of the review. The issue text adds at most 3,000 input tokens by default, and nothing when no issue is linked.
- **Looks for related work when nothing is linked.** If the pull request names no issue, MergeHarbor searches Linear for up to two issues that match the title and uses them as background only (never as requirements, never commented on). Turn this off with **Look for related work**.
- **Cites what it used.** A comment that relied on an issue ends with a "Source used:" line linking to it, and pull request descriptions that MergeHarbor updates get a **Context used** list.
- **Limits.** In **Settings**, restrict the integration to some Linear teams and to some repositories. **Use in pull request conversations** is off by default; when on, people who can read an allowed repository can get answers that use the allowed teams, and turning it off hides earlier answers that relied on it.
- **Shows linked issues in the console** on the pull request page, with links to Linear, the latest requirements check, and the docs read for each issue.

If both Jira and Linear are connected, an identifier goes to the integration whose project or team keys include its prefix.

## Connect

1. In the console, open **Integrations** and choose **Connect** on **Linear**. You need the `settings.manage` permission.
2. Approve access in Linear.
3. Optionally, open **Settings** to choose **Teams to include** (empty means every team the connection can see).

Scopes MergeHarbor requests: `read`, plus `comments:create` only when you connect with write-back.

### API key instead of OAuth

Choose **Use an API key** and paste a key from Linear **Settings → Security & access**. A personal API key reads what its user can read, so use an account with access to the teams you want.

## What is read and stored

- Issue identifier, title, state, labels and description.
- Issue text is cached for a short time (10 minutes by default) and never written to logs. Tokens are encrypted at rest and never shown again.

## Write-back (optional)

Off by default. When on, MergeHarbor comments on each linked issue when a review completes, for example:

> MergeHarbor reviewed PR #12: 2 findings, confidence 4/5. View the review (a link to the pull request in MergeHarbor)

It keeps one comment per issue and updates it on later reviews. If you connected without comment permission, the console asks you to reconnect with it.

## Disconnect

Open the integration in **Integrations** and choose **Disconnect**. MergeHarbor revokes its OAuth token with Linear and deletes its tokens and cached issue text. If you connected with an API key, also delete the key in Linear.

## Self-hosted installations

To offer **Connect** with OAuth, create an OAuth application in Linear (**Settings → API → OAuth applications**):

1. Set the callback URL to `{PUBLIC_URL}/integrations/connect/linear/callback`.
2. Set `LINEAR_OAUTH_CLIENT_ID` and `LINEAR_OAUTH_CLIENT_SECRET` on the API, and make sure `SECRETBOX_KEYS` is set.

Without an OAuth application, teams can still connect with an API key. Optional server settings: `INTEGRATIONS_CACHE_TTL` (default `10m`), `INTEGRATIONS_MAX_TICKETS` (`3`), `INTEGRATIONS_MAX_PAGES` (`2`), `INTEGRATIONS_CONTEXT_TOKENS` (`3000`) and `INTEGRATIONS_FETCH_TIMEOUT` (`8s`).