Connect Linear

To connect Linear to CoIsland you need a personal API key. No admin, no OAuth app and no developer registration: CoIsland calls Linear’s GraphQL API at https://api.linear.app/graphql straight from your Mac, with no CoIsland server or account in between, and keeps the key in your login Keychain. This page covers creating the key, the connector form, the six Linear monitor kinds with filters you can paste, and the errors you may meet.

Create a Linear personal API key

1. In Linear, open Settings › Account › Security & access.
2. Under Personal API keys, create a new key and name it CoIsland.
3. For its permissions, pick Read only. CoIsland never writes to Linear.
4. Optionally, restrict the key to some teams. Monitors then see only those teams, and Test connector says how many teams the key sees, so the restriction is visible.
5. Copy the key. It is shown once.

No Personal API keys section? Workspace admins decide whether members may create keys, under Settings › Administration › API › Member API keys. If it is off, ask a workspace admin to allow Member API keys: CoIsland has no other way in, since OAuth would need an app registered by an admin. Admins can also see and revoke members’ keys there.

A key belongs to one workspace. For several workspaces, add one connector per key.

Connect Linear in CoIsland

Open Settings › Connectors, click + at the top right (or Add Connector when you have none yet), and choose Linear.

Field	What to enter
Connector name	What monitors call it: linear, or your workspace once you type it. Letters, digits, _ and -.
Workspace	Optional: what follows linear.app/ in your Linear address, such as acme. A pasted issue link works too.
Personal API key	The key you created.

Click Test connector, which saves nothing. It asks Linear who the key is, which workspace it belongs to and how many teams it sees, and reads Connected: Ana Silva · ana@acme.com · Acme (acme) · sees 3 teams. When you filled in Workspace and the key belongs to another one, Test says which: pasting the key of the wrong workspace is caught before any monitor runs.

Click Add Connector. The name and workspace go to ~/Library/Application Support/CoIsland/connectors.json, the key to your login Keychain under linear/<name>. CoIsland sends the key as Linear documents it, in the Authorization header with no Bearer prefix, and never follows a redirect.

Choose what to watch: the six Linear monitor kinds

Open Monitors, add a monitor and choose Linear. The issue kinds take Linear’s own IssueFilter, the JSON its API takes, written for you by the fields in the editor (teams, states, priority, assignee, labels, age). A filter the fields cannot show, such as one with or, stays editable as JSON. The inbox and project health take key:value words.

A new-items monitor’s first check records what already matches and raises nothing. Test runs the monitor once and shows what would alert.

Issues

An issue alerts when it starts matching, tracked by its ID. Open issues assigned to you:

{"assignee":{"isMe":{"eq":true}},"state":{"type":{"nin":["completed","canceled"]}}}

Urgent issues in team ENG:

{"priority":{"in":[1]},"team":{"key":{"eq":"ENG"}}}

More filters that work as presets: due within a day {"dueDate":{"lt":"P1D"}}, blocked {"hasBlockedByRelations":{"eq":true}}, joining the active cycle {"cycle":{"isActive":{"eq":true}}}, with customer requests {"customerCount":{"gt":0}}. Priorities are numbers: 1 Urgent, 2 High, 3 Medium, 4 Low, 0 none. Relative dates are ISO 8601 durations: -P1D is a day ago, P1D a day from now.

For a cycle about to end with open work, use the filter below with Alert when set to a count greater than 0:

{"cycle":{"endsAt":{"lt":"P1D"},"isActive":{"eq":true}},"state":{"type":{"nin":["completed","canceled"]}}}

Status changes

An issue alerts each time it lands in a new workflow state, with the state it came from (In Progress → In Review). A state entered more than an hour before the previous check does not alert: the issue came back into your filter, it did not move.

{"team":{"key":{"eq":"ENG"}}}

New in triage

An issue alerts when it enters a team’s Triage. Name the team; triage must be on for it in Linear. Accepting the issue into the backlog alerts nothing.

{"team":{"key":{"eq":"ENG"}}}

SLA at risk (Linear Business and Enterprise)

An issue alerts when its SLA turns high risk, and once more when it breaches. Name the team. To watch other risk levels, add slaStatus yourself:

{"slaStatus":{"in":["MediumRisk","HighRisk","Breached"]},"team":{"key":{"eq":"ENG"}}}

Inbox

Your own Linear notifications: mentions, replies, assignments and the rest, by category. Your 50 newest are read at each check; a notification older than the previous check does not alert.

category:mentions,commentsAndReplies

category:all watches every category.

Project health

A project update alerts when it is posted with a health you pick, at risk and off track unless you say otherwise. Updates of the last 14 days are read.

health:atRisk,offTrack team:ENG

Add project:<slug> to watch one project; the editor lists them.

What a Linear alert shows

In the notch, each issue’s second line reads ENG-123 · In Review · Urgent · Ana · SLA 14:30: its reference, state, priority, owner and deadline. SLA and due times are absolute, so a card read between checks never goes stale. A click opens the alert in CoIsland; Open in Linear is on the alert page.

The alert page shows each issue at once as the monitor saw it, then fills in live from Linear: the current state, labels in their colours, the description and the five latest comments, rendered from Linear’s Markdown with raw HTML and scripts removed. A status alert adds who moved it and the issue’s state history; an inbox alert highlights the comment it is about. Images uploaded to Linear need your key, which never reaches the page, so they show as their alt text.

Rate limits

Linear allows 2,500 requests and 3,000,000 complexity points an hour for each user, across all their keys. A monitor checked every 5 minutes uses 12 requests an hour for its first page of 50 issues, so 20 Linear monitors use about a tenth of the allowance. When Linear says the limit is reached, the check backs off and tries again later; when less than a tenth is left, the monitor warns you first.

A check reads up to 250 issues (5 pages of 50). When more match, nothing is compared and the monitor asks you to narrow the filter.

What a Linear monitor’s watch file looks like

-- name: Assigned to me
-- kind: linear.issues
-- connector: acme
-- every: 5m
-- alert: new-rows

{"assignee":{"isMe":{"eq":true}},"state":{"type":{"nin":["completed","canceled"]}}}

The kinds are linear.issues, linear.status, linear.triage, linear.sla, linear.inbox and linear.project-updates. Changing the filter, the kind or the connector starts a new baseline. Watch files lists every header key.

Troubleshooting Linear connector errors

• The token was refused. Check it has not expired or been revoked. Linear answered AUTHENTICATION_ERROR: the key was revoked or mistyped. Create a new key, add it as a connector and pick it under Runs on.
• This key belongs to workspace X, not Y. The key is from another workspace. Fix Workspace, or paste the right key.
• Rate limited; retry after … Linear’s hourly limit for your account is used up, perhaps by another tool using your keys. Checks resume on their own.
• Linear refused the request: then Linear’s reason, such as a filter field it does not know. Fix the JSON; the fields in the editor always write a valid filter.
• Pick a team: triage is watched team by team. Add a team to a New in triage or SLA at risk monitor.
• It was deleted or is not visible to this key. On the alert page: the issue was deleted, or the key cannot see its team.
• No Linear connector is named acme. A monitor’s -- connector: line names a connector that does not exist.
• A filter on a team the key cannot see returns no issues, without an error. Test connector shows how many teams the key sees.
• An archived issue leaves a monitor quietly; unarchived and matching again, it alerts again.

Common questions

Does CoIsland need a Linear admin?

No, unless your workspace turned off Member API keys. A member creates a personal key in their own account settings.

Can CoIsland change my Linear issues?

No. It only reads, and a Read key is all it needs. The key stays in your login Keychain and goes only to api.linear.app.

Which filters can a Linear monitor use?

Any IssueFilter Linear’s API accepts, as JSON. The editor writes the common ones for you and keeps anything else as text.

Next: Getting started, or the Linear connector for everything it can watch.