Connect Linear
Bring your team's Linear issues to the agent with a personal API key. Approved replies and the agent's findings go back as comments on the issue.
Linear is an issue tracker: your team's own list of work. Connect it, and new issues your team opens in Linear reach the agent. Approved replies go back as comments on the issue. So can the agent's findings, if you want them.
Everyone in your workspace sees the comments
Linear has no private comments. Every reply and finding we add to an issue is a normal comment. Everyone in your Linear workspace who can see the issue can read it.
A platform has one ticket system at a time. If this platform uses another one, disconnect it first. See Connect your ticket system.
Before you start#
- A Linear member for the key. Comments we add show as written by the person whose key it is. Best: a member used only for this, such as one named "Cerberius Agent". Comments by that person never count as replies from the person who opened an issue.
- A Linear admin, to add the webhook (a web address Linear calls when an issue changes).
Connect Linear#
- 1
In Linear, sign in as the member the comments should come from. Go to Settings › Account › Security & access. Under Personal API keys, click New API key and give it a name. Give it Read and Write permission, and access to the teams this platform takes. It needs no admin rights. Create it, and copy the key. It starts with
lin_api_, and Linear shows it only once. Show me how on our page shows these steps too. - 2
Here, go to Settings › Ticket system. On the Connection tab, click Connect a ticket system and choose Linear.
- 3
Under Your Linear, paste the key into Personal API key.
- 4
Under Which issues, click Show my teams. Tick the teams whose issues come to this platform. To take only some issues, type a label into Only issues with this label, for example
Support. - 5
Under Replies and findings, choose whether to Add the agent's findings as a comment.
- 6
Click Connect Linear. Then click Check connection.
- 7
In Linear, a Linear admin goes to Settings › API, and under Webhooks clicks New webhook. Paste the Webhook address from Let Linear tell us about new issues on our page as the URL. Choose the team, or All public teams. Tick the data change events Issues and Issue comments, then save the webhook.
- 8
Open the webhook in Linear and copy its Signing secret. Paste it into Linear's signing secret on our page, and click Save the secret. Until you do, the page warns that calls aren't checked.
- 9
Try it. Create a test issue in one of the ticked teams. It shows under Tickets here within a minute, and our page says Last heard from Linear with the time.
For more than one team, make one webhook for All public teams. Each webhook in Linear has its own signing secret, and we keep one. Issues of teams you didn't tick are read and then left out.
Settings#
| Setting | What it does |
|---|---|
| Personal API key | The key we read issues and add comments with. We try a new key with Linear before saving it, and a key Linear refuses is not saved. Once saved, it is never shown again. Paste a new one to replace it. |
| Workspace and key owner | Show once Linear is connected: your Linear workspace, and the person comments show as written by. |
| Check connection | Shows once Linear is connected. It asks Linear who the key belongs to, and says whether that worked. |
| Which issues | The teams whose issues come to this platform: the teams whose systems this platform can look into. Tick at least one. A team that another of your platforms takes can't be ticked, and says which platform takes it. Two platforms never take the same team. |
| Only issues with this label | Optional. Only issues with a label of this name come in, in any mix of capitals. Linear's labels are offered as you type. Leave it empty to take every issue of the ticked teams. An issue that gets the label later comes in then. |
| Webhook address | Shows once Linear is connected. Paste it into Linear, with Copy. Keep it private. We only ever read the issue with your key, and take only your chosen teams' issues. |
| Linear's signing secret | Linear signs every call with it. Once saved, we refuse calls without Linear's signature, or sent more than 5 minutes before they reach us. It is never shown again. Paste a new one replaces it; Remove it stops the check. |
| Last heard from Linear | When Linear last called the webhook address. Never yet means it hasn't called: check the steps. If a call was refused, it says when and why, such as wrong signature. |
| Add the agent's findings as a comment | When on, a comment with what the agent found and what it proposes goes on the issue as soon as a reply is ready to approve. Everyone in your Linear workspace can see it. Off at first. |
Once Linear is connected, change anything here and click Save at the bottom.
What happens with an issue#
- A new issue in a ticked team, with the label if you chose one, reaches the agent with the images and files in its description. The person who opened it in Linear is the requester. What they added in comments before it reached us is part of the request.
- A comment by the person who opened it reaches the agent as a follow-up, with its images and files. Comments by anyone else, and by the key's owner, are skipped.
- Moving it to a done or cancelled state in Linear stops the work here.
- An approved reply becomes a comment on the issue. Nothing else on the issue changes.
- Closing it here moves the issue to the team's first done state, usually Done. An issue done or cancelled in Linear already stays as it is.
Some issues don't come in:
- Issues opened before you connected Linear. Linear tells us about every change to every issue, and older work someone moves or edits is not new work for the agent.
- Issues already done or cancelled when Linear first tells us about them.
- Issues of teams you didn't tick, or without your label.
The ticket page shows the issue as Linear has it now: its status, who it is assigned to, its team, priority, project and due date, with Open in Linear.
Only tickets that came from Linear go back to Linear. Other tickets on the same platform, from the log watcher for example, don't.
Stop#
Click Disconnect… at the top of the Connection tab, and confirm. New issues from Linear stop coming in, and replies stop going back to it. The webhook address stops working at once. Tickets already here stay. To be tidy, delete the webhook in Linear too, and revoke the key under Settings › Account › Security & access.