incident.io
Connect
Connect incident.io from the terminal. Pass --help for the flags incident.io accepts.
polylane integration connect --type incident_ioAn API key from Settings → API keys in incident.io.
Connect your incident.io organization with one API key.
- In incident.io API keys, create an API key with the roles listed under Roles.
- Paste the key into Polylane. Polylane checks it and shows what the key turns on, and names the role a feature needs when that role is missing.
On connect, Polylane creates a workflow named "Polylane: investigate incidents (your workspace name)", a workflow secret, and an HTTP alert source named "Polylane" in incident.io. Disconnecting deletes all three.
How it works
Incidents start investigations
Every new live incident in incident.io starts a Polylane investigation. Private and test incidents are skipped. The workflow that Polylane creates sends the incident ID to Polylane the first time the incident is live. Polylane reads the incident back through the API and starts one investigation for it. A second notice for the same incident does not start a second investigation.
incident.io does not send a failed notice again. To catch a missed notice, Polylane also checks for live incidents every five minutes. It starts an investigation for each public, standard incident from the last 24 hours that does not have one.
When Slack is connected to Polylane and the incident's Slack workspace is the same, Polylane joins the incident channel and posts its findings there. Replies in that channel go to the same investigation. If Polylane cannot join the channel, the findings stay in the Polylane thread.
Escalations become incident.io alerts
When Polylane cannot resolve an issue, it raises an escalation and grades it as critical, high, medium or low. Polylane sends an escalation to incident.io as an alert when its grade is at or above the level you set on the integration page. The default level is high. The grade of the escalation is what counts, not the severity of the issue.
Polylane does not declare incidents itself. The alert goes to the "Polylane" alert source. Your alert routes in incident.io decide what happens next. An alert pages no one and opens no incident until you add the Polylane alert source to an alert route.
The escalation ID is the deduplication key of the alert:
- When you mark the escalation as handled, or delete it, Polylane resolves the alert.
- When you reopen the escalation, Polylane fires the alert again.
- When the same escalation occurs again while its alert is open, incident.io keeps one alert and does not page again.
These escalations never go to incident.io: escalations about credentials or connecting an account, escalations that have no issue, and escalations without a grade. An escalation that a person raises through the API has no grade.
When an alert route opens an incident from a Polylane alert, Polylane does not start a second investigation. It adds a note to the thread of the escalation, so the work stays in one place.
Catalog and tools
Polylane maps your incident.io catalog services into the context graph and links them to their repositories. During an investigation, agents read incidents, updates, follow-ups and on-call schedules. Agents can also request changes to incident.io, such as an incident update or a page to an escalation path. Each change needs safety review and approval before it runs.
Roles
Polylane uses these incident.io roles. A feature whose role is missing stays off, and the integration page names the role.
| Role | What it unlocks |
|---|---|
viewer | Reads incidents, updates, follow-ups, and the catalog, and maps catalog services into the context graph. Required. |
schedules_reader | Reads on-call schedules to tell who is on call. |
workflows_editor, secrets_manage | Creates the workflow that starts an investigation for each new incident. |
on_call_editor | Creates the Polylane alert source that receives unresolved escalations. |
incident_editor, incident_creator | Creates and edits incidents and posts updates, after safety review and approval. |
escalation_creator | Pages an escalation path, after safety review and approval. |
Disconnecting
Disconnecting deletes the workflow, the workflow secret and the alert source that Polylane created. It leaves the API key in incident.io. Remove it under Settings → API keys in incident.io.
Disconnect
Disconnecting stops every sync and check and deletes the credentials Polylane held. Polylane removes what incident.io's API lets it remove. The following stays until you remove it yourself:
- incident.io API key
polylane integration disconnect <id>Tools
4Operations agents can perform in threads.