Connect Linear to Qoren

Connect Linear once with a personal API key and your agents can wake when an issue is created, updated, moves to another status or is assigned, or when someone comments. Qoren creates the Linear webhooks itself, so there is nothing to copy into Linear's settings.

The same connection lets the agents you choose find and read issues and, if you allow it, create issues, comment and change an issue's status, assignee or priority. Archiving always waits for your approval. How connections, access and approvals fit together is in connect your tools with Integrations.

Before you start#

• You are the owner of your Qoren organization. Only the owner connects tools, gives agents access and sends connect links.
• Integrations is on for your account. It is rolling out: if the sidebar has no Integrations under Capabilities, it is not on your account yet.
• For triggers, the key is made by a Linear workspace admin. Linear only lets workspace admins create webhooks. Agents can still read and write with a member's key, but triggers will not work with it.
• Your workspace lets you create personal API keys. Admins can switch member keys off in Linear's API settings.

Make the key#

1. In Linear, open Settings, Security & access and create a new personal API key named Qoren (open it in Linear).
2. Choose its permissions, the least that does the job:

• Admin if Qoren should set up triggers. Linear needs it to create webhooks.
• Read if agents only look things up.
• Write, Create issues or Create comments only if agents should change things.

3. Limit the key to the teams your agents work on.
4. Copy the key. Linear shows it once.

Linear does not tell Qoren which of these permissions a key has, so choose them with care. If you want agents to stay read only, make the key Read in Linear as well as choosing Read only in Qoren.

Connect it in Qoren#

1. In the sidebar, under Capabilities, click Integrations.
2. Under Add a tool, click Linear. The Connect Linear dialog shows the same steps as above.
3. If you run an agency, choose the client in Which client is this for?, or leave No client (your own account).
4. Paste the key into API key.
5. Click Check key. Under Key checked you see the workspace (Account:), Can read and whether it Can add webhooks.
6. Under What agents may do, choose Read only or Read and write.
7. Click Connect.

The screens are shown step by step in connect a tool.

What Qoren checks#

• That Linear accepts the key, and which workspace and user it belongs to. The workspace name becomes the connection's label.
• Which teams the key can see.
• Whether it can manage webhooks, by listing the workspace's webhooks, which Linear allows only for admin keys. If it cannot, the check tells you why: the key needs the Admin permission, or its user is not a workspace admin.
• Whether its user is a guest, who only sees the teams they were invited to.

Whether the key can write is not something Linear reveals, so the check cannot tell. A write the key is not allowed to make fails with a clear message.

Give an agent access#

A new connection is used by no agent until you give one access. Open the connection under Connected, choose an agent (or all agents) in Give access to…, pick Read only or Read and write, and click Give access. See give an agent access.

Events#

Create triggers from these on the agent's Triggers tab; see wake an agent from a connected tool.

What the agent receives. The event, the action, a link to the issue, who did it and when, then a summary of the issue (identifier, title, description, status, priority, team, assignee, labels) or of the comment, plus what changed and its earlier values. Long text is shortened.

How the webhook is set up. Qoren creates one Linear webhook for issues and one for comments, as each is needed, covering all public teams and signed with a secret only Qoren and Linear know. Each delivery's signature and its signed timestamp are checked; a delivery older than five minutes is refused. A retry of the same change is recognised and runs the agent once.

Tools agents can use#

Writes need a Read and write grant and follow the agent's autonomy. Archiving always waits on the Approvals page. The limits Qoren puts on every connected tool, such as how many records an agent may read an hour, are in how Qoren keeps connected tools safe.

Limits and gotchas#

• Only public teams wake agents. Qoren's webhooks cover all public teams. Changes in private teams do not arrive as events, although the tools can still read private teams the key can see.
• Admin for triggers. Without a workspace admin's key with the Admin permission, no trigger can be created.
• Linear switches off failing webhooks. If deliveries keep failing, Linear may disable a webhook. Qoren's daily check sets up again any webhook of its own that was deleted, switched off or changed.
• Key permissions are invisible to Qoren. Qoren holds agents to the level you grant, but cannot confirm what the key itself allows.

Troubleshooting#

• "Linear did not accept this key." Copy the whole key again, or make a new one: Linear shows a key only once.
• "Only Linear workspace admins can manage webhooks, and the key needs the Admin permission." Ask an admin to make a key with Admin, then click Replace key.
• A team's issues never wake the agent. The team may be private, or outside the teams the key is limited to.
• "This team has no status called that." The agent named a status that team does not have; the answer lists the ones it does.
• The connection says Needs a new key. The key was revoked or its user removed. Its triggers are paused until you click Replace key. See when a connected tool stops working.

Disconnect and delete the key#

1. On the Integrations page, open the Linear connection under Connected.
2. Click Disconnect, then Disconnect again in the Disconnect Linear? dialog (or Keep it).

Qoren deletes the stored key, removes the webhooks it created in Linear, removes every agent's access and pauses the triggers that used the connection.

Qoren cannot revoke a Linear key, so revoke it in Linear too: open Settings, Security & access and revoke the key (open it in Linear).