Integrations

Integrations connect Unhandled to the tools your team already works in. There are two kinds: issue trackers, which turn an exception into a ticket and resolve it when the ticket closes, and notification channels, which post alerts where people will see them. Both live on the organization's Integrations settings page (/o/:org/settings/integrations), and only organization admins can change them.

Unhandled has no integration with PagerDuty, Opsgenie, Microsoft Teams or Jira yet. A signed webhook channel is the way to reach them; see Notifications.

Issue trackers

Each organization connects at most one GitHub installation and one Linear workspace.

1. An admin clicks Connect next to GitHub or Linear and completes the flow on the provider's side. The row then shows Connected with the account name.
2. If Linear revokes the grant (it answers invalid_grant to the refresh token), the row shows Reconnect instead of Connected, and creating or linking Linear issues says "Linear needs to be reconnected". Reconnect runs the Linear flow again and keeps the project mappings. Connections made before Linear issued refresh tokens have nothing to refresh, so they only show this after the first request Linear refuses. A wrong LINEAR_CLIENT_ID or LINEAR_CLIENT_SECRET, a Linear outage or a network failure says "Linear is unavailable" instead and leaves the stored tokens alone, so fixing the setting is enough.
3. Configure opens a dialog that maps each project to one GitHub repository or one Linear team. New tickets created from that project go there.
4. On any issue, the menu offers Create or link GitHub issue and Create or link Linear issue for every connected provider. Create new opens a ticket; Link existing searches the provider or takes a reference you type.

A created ticket gets the issue title, which you can edit first, and a body with the exception type and message, the application (project) name, its environments, first and last seen times, and a View in Unhandled link back to the issue. Creating a ticket fails with a clear message when the project has no mapped repository or team. Only organization admins can create or link a GitHub issue in a repository other than the project's mapped one.

Every link and unlink is recorded in the issue's activity under the user who made it. An issue can hold links to both providers, and you can unlink from the same menu.

Status sync

Each provider sends Unhandled a signed webhook when a ticket changes. When a linked ticket is closed (GitHub) or moves to a completed state (Linear), Unhandled resolves the issue and records it as resolved externally. This only applies to issues that are open or archived for a limited time; an issue you already resolved or archived forever is left alone.

Sync runs one way. Resolving an issue in Unhandled does not close the ticket, and reopening a ticket does not reopen the issue. If the exception comes back after the issue was resolved, the issue regresses as usual.

Disconnecting

Disconnect removes the connection. Project mappings and existing links are kept, so connecting the same account again picks up where you left off. Uninstalling the Unhandled GitHub App on GitHub removes the GitHub connection too.

Notification channels

The same page lists the organization's notification channels with the defaults they are used for, how many alerts, monitors and exception rules post to them, and whether a channel is failing or was disabled after 10 failed attempts in a row. Add channel creates a Slack, Discord or webhook channel from a name and a URL, with a Send test button to try it before saving. The Notifications page explains routing, defaults and delivery; the Slack and Discord pages cover their message formats.

Self-hosting

GitHub and Linear need provider credentials in the server's environment. Without them, Connect fails and inbound webhooks are rejected.

The provider pages list the callback and webhook URLs to register.