Sentry

Sentry is a deep App integration, in the same family as GitHub and GitLab: it is entity linking plus status sync, and it needs no AI. It links Sentry errors to work items and keeps their status in step.

What it does

• Search a Sentry organization's error groups from the issue detail panel and link one (or several) to the work item.
• Store a snapshot of each linked error (short id, title, permalink, status, level, last seen) so the panel renders without a live Sentry call.
• Refresh a linked error's snapshot on demand from Sentry.
• Receive signed Sentry issue webhooks and move the linked work item through a status mapping when the error is resolved, ignored, or reopened.

Layers

Sentry has no instance layer and no shared app credential to configure. You create one Sentry internal integration per Sentry organization and connect it at the workspace layer.

Layer	Who	Where
Workspace	Workspace admin	Workspace settings -> Integrations -> Apps tab, the Sentry card, its Configure button (/{workspace}/settings/integrations)
Project	Any member	The issue detail panel, the "Sentry issues" section

Everything on the Ithura side lives in one place: the Sentry card on the Apps tab. Its Configure button opens a single "Configure Sentry" modal that holds the token, the webhook signing secret, and the status-sync mapping together. There is no separate Connectors tab and no standalone status-mapping card.

Provider setup (Sentry, once per organization)

In Sentry, create an internal integration: Settings -> Developer Settings -> Custom Integrations -> New Internal Integration. Set a name (for example "Ithura"). This integration produces two things Ithura needs:

1. An auth token, org-scoped, sent as Authorization: Bearer <token>. Grant these scopes (read-only is enough, because Ithura never writes to Sentry):
   • org:read
   • project:read
   • event:read
2. A client secret (the integration's webhook signing secret), used to sign every webhook delivery. Sentry shows it under Credentials once the integration is saved.

In the same integration, set the Webhook URL to your workspace ingress and subscribe to the issue resource:

https://<api-host>/webhooks/sentry/<workspace-slug>/

For the hosted product that is https://api.ithura.com/webhooks/sentry/<workspace-slug>/. Ithura acts only on issue events; it acknowledges any other resource (for example comment or event_alert) without acting on it, so Sentry does not retry them.

Connect (workspace admin)

Open Workspace settings -> Integrations, stay on the Apps tab, find the Sentry card, and click Configure. The "Configure Sentry" modal holds:

• Name: a label for this connection.
• Base URL: https://sentry.io for Sentry SaaS (the default). For self-hosted Sentry, use your own host (for example https://sentry.example.com); Ithura appends the /api/0/ path itself.
• API token: the internal-integration auth token from above. Stored encrypted, shown masked afterwards. Leave the mask in place to keep the stored token.
• Webhook signing secret: the integration's client secret. Stored encrypted, used to verify inbound webhook signatures.

Click Save. The modal then adds a Test connection button (it runs a live handshake against Sentry and reports "Connection OK"), an Enabled toggle, and a Remove button. Once the connector row exists, the modal also shows the Status sync section described below.

The token, the base URL, and (once known) the organization slug are all stored on the workspace's Sentry connector row.

Organization

Ithura needs one Sentry organization slug to scope searches. The first time it lists organizations for the token and the token can see exactly one, that org is saved automatically. If the token can see several, pick one and Ithura stores the choice. Everything else (search, link, refresh) uses that organization.

Using it, on a work item

Open a work item and find the Sentry issues section on the issue detail panel. From it you can:

• Search the connected organization's error groups and attach one with the + control. The organization is taken from the connector, never from your input.
• See each linked error with its short id, title, status, and a link out to the error in Sentry (its permalink).
• Refresh a link to re-read its current status and metadata from Sentry. Refresh is debounced to about a minute; the explicit refresh control bypasses the debounce.
• Remove a link. Removing and re-linking the same error reuses the same row.

Viewing the panel needs Guest access; linking, refreshing, and removing need the Member role. The section only appears when the workspace has an enabled Sentry connector, so there is no dead entry when Sentry is not set up.

Status sync (Sentry -> Ithura)

When a linked error changes state in Sentry and Sentry delivers the issue webhook, Ithura verifies the signature, updates every linked work item's stored snapshot, and moves each linked work item through the status mapping.

Built-in defaults

With no mapping saved, these defaults apply:

Sentry status	Work item moves to	State group
resolved	Done	completed
ignored	Cancelled	cancelled
unresolved (reopened)	No change	none

A group resolves to the project's first state in that group, so it works even though every project names its states freely. If a project has no state in the target group, the work item does not move. A work item is only moved when the resolved target differs from its current state. Entering the completed group stamps the completion date; leaving it clears it, matching a completion done by hand.

Sentry's status vocabulary is folded onto three values: resolvedInNextRelease counts as resolved; muted and archived count as ignored; unignored, reopened, and unresolvedInNextRelease count as unresolved.

Changing the mapping

The mapping lives in the Status sync section of the same "Configure Sentry" modal, below the webhook signing secret. It is workspace-level: three rows, one per Sentry status, each with a state-group selector:

• When resolved in Sentry moves to Done by default.
• When ignored or archived in Sentry moves to Cancelled by default.
• When reopened (marked unresolved) in Sentry is set to No change by default, so a flapping alert never yanks a work item backwards on its own.

Set each row to a state group or leave it as "No change", then click Save status sync. A target group must be one of backlog, unstarted, started, completed, cancelled, or triage. Reading the mapping needs the Member role; changing it needs the Admin role. Saving replaces the workspace mapping as a whole.

How ingress is held

Every delivery is written to a durable queue and de-duplicated on its delivery id (the Request-ID header, or a timestamp-plus-resource composite when that header is absent), so a Sentry redelivery is safe and no event is applied twice. The receiver verifies the Sentry-Hook-Signature (an HMAC-SHA256 of the body with your stored client secret) and returns immediately; the status move happens in a background worker with retries.

Tutorial: connect Sentry and triage errors from Ithura

You need a Sentry organization you administer. This walkthrough creates a real internal integration, so completing it end to end requires that Sentry org and the token and client secret it issues.

1. Create the internal integration. In Sentry, go to Settings -> Developer Settings -> Custom Integrations -> New Internal Integration. Name it (for example "Ithura"). Under permissions, set Issue and Event to Read (this covers org:read, project:read, and event:read). Under Webhooks, subscribe to the issue resource and set the Webhook URL to https://<api-host>/webhooks/sentry/<workspace-slug>/. Save.
2. Copy the auth token. The integration page shows an auth token. Copy it.
3. Copy the client secret. On the same page, under Credentials, copy the integration's client secret; this signs the webhooks.
4. Open the Sentry card in Ithura. In Ithura, go to Workspace settings -> Integrations, stay on the Apps tab, find the Sentry card, and click Configure.
5. Fill the modal and save. Set the base URL to https://sentry.io (or your self-hosted host), paste the auth token into API token, paste the client secret into Webhook signing secret, and click Save.
6. Test the connection. Click Test connection; it should report "Connection OK". If the token sees only one organization, Ithura selects it for you; otherwise pick one when prompted.
7. Set the status sync (optional). In the same modal, review the Status sync rows (resolved, ignored, reopened) and click Save status sync if you change a target. The defaults send resolved to Done and ignored to Cancelled.
8. Link an error. Open a work item, find the Sentry issues section, click +, search for an error group, and attach it. The panel now shows its status and a link out.
9. Watch the sync. In Sentry, resolve that error. Sentry delivers the issue webhook, and the linked work item moves to Done (or wherever your mapping sends "resolved"). In testing this moved a linked Backlog item to Done within a couple of seconds.

Troubleshooting

Symptom	Cause	Fix
The Sentry issues section is empty or hidden	No enabled Sentry connector with a token for the workspace	Configure the Sentry card under Settings -> Integrations -> Apps, then enable it
"Sentry rejected the connector token"	The token is wrong, revoked, or missing scopes	Re-issue the internal-integration token with org:read, project:read, event:read and paste it again in the Configure Sentry modal
Search says no organization is set	The token can see several orgs and none is chosen	Pick an organization from the org list, then search again
A resolve in Sentry does not move the work item	The webhook is not reaching Ithura, or the signature fails, or the status maps to "No change"	Check the webhook URL and the issue subscription in Sentry, confirm the client secret matches the modal's Webhook signing secret, and review the Status sync rows
Duplicate deliveries	Sentry retried a delivery	No action needed; deliveries are de-duplicated on their id

Boundaries

• Live linking, search, and status sync need a real Sentry organization and a real internal integration (token plus client secret plus a reachable webhook URL). There is no way to exercise the live flow without one.
• Self-hosted Sentry works by setting the base URL to your host; region-pinned SaaS orgs that resolve to a region host can set the base URL to that host.
• Ithura reads from Sentry and receives its webhooks; it does not resolve, ignore, or otherwise change issues in Sentry.
• Only the issue webhook resource drives automation today. Comment mirroring and auto-creating work items from alerts are not wired up. </content>

</invoke>