Linear plugin

Opens a Linear issue for each new Mushi Mushi report and updates it once the report is triaged.

Most people don’t need the plugin. Connect Linear on the console’s Integrations page (OAuth or a pasted API key) and Mushi Mushi files Linear issues and closes them for you. The plugin below is for running the Linear calls from your own server.

Setup (self-run plugin)

Create a Linear API key: Settings → Security & access → Personal API keys → New key.

Start the server where Mushi Mushi can reach it over public HTTPS:


npm i @mushi-mushi/plugin-linear
export MUSHI_PLUGIN_SECRET=...      # must match the signing secret in step 3
export LINEAR_API_KEY=lin_api_...
export LINEAR_TEAM_ID=...           # the Linear team to file issues under
npx -p @mushi-mushi/plugin-linear mushi-plugin-linear

In the console: Marketplace → Linear Sync → Install. Set the webhook URL to https://<your-host>/mushi/webhook. Keep the signing secret Mushi Mushi generates (or paste your own) and use the same value for MUSHI_PLUGIN_SECRET.

Behaviour

Event	Action
`report.created`	Creates a Linear issue (title, plus the event JSON in the description)
`report.classified`	Updates that issue’s title and description
`report.status_changed`	Moves the issue to the state in `stateMap[newStatus]`, if you passed a `stateMap` (programmatic use only)

The report → issue mapping is kept in memory unless you pass your own cache to createLinearPlugin(cfg, cache), so a restart can lead to a second issue for the same report.

Troubleshooting

Issues not created: check the plugin’s last delivery status on the Marketplace page. A 401 from your server means the signing secret differs from MUSHI_PLUGIN_SECRET; a Linear error in your server log usually means the API key or LINEAR_TEAM_ID is wrong.
Duplicate issues: see the in-memory mapping above, and check you have not connected Linear both on the Integrations page and through this plugin.