Triage for Jira

Setting up Triage for Jira

Takes about ten minutes. You'll need to be a Jira admin, and an owner or manager in Sentry, since Sentry only lets those roles create integrations.

One thing to know before you start, because it explains the shape of the setup: this app never calls Sentry. Sentry calls it. You give Sentry a URL and Sentry starts delivering to it. That's why the app works on Sentry's free Developer plan, why self-hosted Sentry needs no firewall changes, and why it qualifies for Atlassian's Runs on Atlassian badge.

1. Create a connection

Go to Apps → Triage for Jira → Setup.

Name the connection after the Sentry organisation it represents, something like "Acme production". If you run Sentry yourself rather than on sentry.io, put its address in the optional URL field. That address is only used to build links you can click; nothing is ever sent to it.

Click Create connection. A webhook URL appears in step 2. Copy all of it, including the long id on the end.

You need one connection per Sentry organisation. A connection attaches itself to the first Sentry organisation that posts to it and then refuses every other one, which is what keeps two organisations' data apart. It can't be reassigned afterwards, so a second organisation needs a second connection with its own URL.

2. Create the integration in Sentry

In Sentry, go to Settings → Integrations, click Create New Integration at the top right, and choose Internal.

Sentry has moved this page more than once. If the button isn't where you expect, look for Custom Integrations in the settings sidebar, which is where internal integrations live once they exist.

Give it a name you'll recognise later, like "Triage for Jira". You'll pick it from a dropdown in step 4, so make it obvious. Paste the webhook URL from step 1 into the Webhook URL field.

Now the order matters:

1. Under Permissions, set Issue & Event to Read. Do this before you look at the webhook checkboxes, because Sentry leaves them greyed out until a scope grants access and doesn't tell you why.
2. Tick the Issues webhooks, including Created, Resolved, Assigned, Archived and Unresolved.
3. Turn on Alert Action.
4. Save.

You'll see the Errors checkbox greyed out unless you're on a Business or Enterprise plan. Leave it alone. This app doesn't use it. Events get here through the alert you set up in step 4, which every Sentry plan has including the free one. The Errors webhook is an unfiltered stream of every event; going through an alert instead is what lets your rules decide what becomes a work item.

Once you've saved, copy the Client Secret. Not the Client ID. They sit next to each other and look alike, and mixing them up is the most common setup mistake by some distance.

3. Paste the Client Secret back

Go back to Apps → Triage for Jira → Setup, step 3, and paste it in.

If you have more than one connection, check the picker in step 1 is naming the right one first. Stored secrets are never shown back to you, so pasting into the wrong connection breaks it quietly.

The secret goes into Forge's encrypted store. It's used to check the signature on incoming webhooks and nothing else. It gives the app no access to your Sentry data.

4. Connect an alert to your project's error monitor

This is the step people skip, and nothing arrives without it. Creating the integration doesn't deliver anything on its own.

In Sentry, go to Monitors, open your project's Error Monitor, find Connected Alerts and click Create a New Alert. Sentry makes one error monitor per project automatically, so there's nothing to create there, only the alert.

Set it up like this:

• WHEN: A new issue is created. Remove the other triggers.
• IF: Any event.
• THEN: Send a notification via your integration.
• Action Throttle: Get notified on every trigger.

Two of those are worth explaining.

Trigger on new issues only. Resolved, escalated and regressed errors already reach the app through the Issues webhooks you ticked in step 2, and those are what keep Jira statuses in step with Sentry. If you leave them switched on as alert triggers too, resolving an error in Sentry sends it here a second time as another occurrence. That inflates the error's event count and adds a comment nobody asked for.

Leave the throttle on every trigger. Any other setting makes Sentry hold back repeat notifications, and repeat notifications are what the app counts and deduplicates on.

5. Choose your projects

Go to Apps → Triage for Jira → Projects and tick the Jira projects that should show Sentry data. Everything is off until you turn it on.

Panels don't appear by themselves in Jira. To open one on a work item, click the Apps button, the hexagon under the title next to the plus sign, and choose Sentry error. Ticking a project here doesn't make a panel show up on its own. If you open the panel in a project you haven't ticked, it tells you so rather than showing you anything.

6. Create a mapping rule

Go to Rules and click New rule. A rule decides which errors become work items, and where they land.

Rules run top to bottom and the first one that matches wins. A rule sitting underneath a broader one can never fire, so the Rules tab marks those "never runs" and tells you which rule is in the way.

Each rule belongs to one connection. If you add a second Sentry organisation later, it needs its own rule as well as its own connection.

The hourly cap is worth leaving on. Deduplication only helps when the same error repeats. A bad deploy produces hundreds of different Sentry issues in a few minutes, each with its own id, each matching the same rule, and without a cap you get hundreds of tickets during the hour you can least afford them. Errors the cap drops stay in Sentry and show up in the delivery log with the reason, so nothing is lost.

7. Watch the first event arrive

Trigger an error in the Sentry project, or just wait for a real one.

The Setup tab moves the connection to Connected on its own, without a refresh, and step 4 turns green once an alert has actually delivered something. The Dashboard's delivery log lists every webhook that arrived and what it did with it: created, deduped, filtered, throttled or ignored, each with a reason.

If the Setup tab shows Signature mismatch, deliveries are arriving but the Client Secret doesn't match. Copy it again from Sentry, checking you've taken the Secret and not the ID.

If your Jira project is team-managed

Team-managed projects don't inherit global custom fields. Work items still get created properly, but Sentry Error Count and Sentry Issue read as empty and nothing logs an error, which makes this annoying to work out from scratch.

Two steps fix it:

1. Project settings → Fields, and add Sentry Error Count and Sentry Issue.
2. Project settings → Work types, pick your work type, drag both fields onto the layout, and save.

Company-managed projects pick these up on their own. The app warns you on the Rules tab when it can tell a rule's target project is missing them.

The JQL names sentryIssueId and sentryEventsSinceInstall work in both kinds of project with no setup at all, because they come from an indexed issue property rather than a custom field.

More than one Sentry organisation

Each one needs its own connection, its own integration in Sentry, its own alert and its own rule. They share nothing. Work items, counters and rules are kept apart by the Sentry installation id, which you can see on the Connections tab.

Self-hosted Sentry

Works the same, with nothing extra to configure. Since the app never calls Sentry, there's no allowlist to edit and no inbound path to open: your Sentry instance makes an outbound call to Atlassian and that's the whole story. Put your base URL on the connection so links point at the right place.

Removing the app

Uninstalling deletes everything the app stored, including connections, the encrypted Client Secrets, rules, links and counters. Work items it created stay where they are, because they're ordinary Jira work items.

If you only want to stop deliveries, remove the connection on the Connections tab instead. To stop one rule, switch it off.