Connect Sentry

To connect Sentry to CoIsland, you create a personal token with read access, add it as a Sentry connector for one organization, then pick what to watch: any issue search, regressed and escalating issues, issues assigned to you, cron, uptime and metric monitors that trip, or new releases. It works on sentry.io, in the US or the EU region, and on a self-hosted Sentry.

CoIsland calls Sentry’s API straight from your Mac: there is no CoIsland server and no CoIsland account. The token stays in your login Keychain, and every request the Sentry connector sends is a read.

Create a personal token with read access

Any member of an organization can create a personal token, with no admin and no integration to set up. The token is bound to you and never reaches further than your own permissions. On Sentry:

1. At sentry.io, or your self-hosted address, open your account menu, then User settings › Personal Tokens, and Create New Token.
2. Name: one you will recognize, such as CoIsland.
3. Permissions: set Read on Organization, Project, Issue & Event and Alerts. Leave everything else at No Access. Scopes cannot be changed once the token exists.
4. Create it and copy it. A personal token starts with sntryu_.

Which permission each monitor kind needs

Monitor kind	Scope	What CoIsland calls
Test connector	Organization: Read	GET /api/0/ and the organizations the token sees
Issue search, Regressed & escalating, Assigned to me, Crons, uptime & metric	Issue & Event: Read	The organization’s issue search, then the issue and its latest event
New releases	Project: Read	The organization’s releases, then the release and its deploys
Project and environment suggestions in the editor	Organization: Read	The organization’s projects

Alerts: Read is not needed today; it keeps the token ready for monitor details.

Organization tokens do not work

An organization token (Settings › Developer Settings › Organization Tokens, starting sntrys_) is made for CI: it uploads releases and source maps and cannot read issues. CoIsland refuses one with “This is an organization token, made for CI: it cannot read issues. Create a personal token.” Internal integrations need an organization manager or owner, so CoIsland does not ask for one.

When your organization limits personal tokens

With Sentry’s default settings, any member can read the issues of their teams’ projects, and join any team while Open Membership is on. An organization that enforces single sign-on, or limits personal tokens, may refuse yours; CoIsland then shows Sentry’s own words and says so: “Not allowed: …; it needs Read on Organization, Project and Issue & Event, or your organization may not allow personal tokens (ask an owner).” Only an owner can change that.

Connect Sentry in CoIsland

1. Open Settings › Connectors and click + (Add Connector).
2. On Add a connector, choose Sentry.
3. Fill in the four fields, then click Test connector.
4. Click Add Connector.

Field	What to enter
Sentry address	Leave sentry.io for sentry.io, whichever region your data lives in, or enter your self-hosted Sentry, such as https://sentry.example.com
Organization	Its slug, as in sentry.io/organizations/acme or acme.sentry.io
Connector name	What monitors call it: letters, digits, _ and -, starting with a letter. CoIsland suggests the organization’s slug
Personal token	The token you copied, with no spaces or line breaks

Test connector asks Sentry who the token belongs to and which scopes it has, then finds the organization and the region it lives in (us.sentry.io or de.sentry.io). It saves nothing. On success it shows your name and email, the organization with its region, and the token’s scopes, and warns when a read scope is missing. When the slug is wrong, it lists the organizations the token sees.

Add Connector keeps the address, the organization and its region in ~/Library/Application Support/CoIsland/connectors.json, and the token in your login Keychain, never in a file. The first Sentry connector becomes the default: a monitor that names no connector runs on it.

Watch Sentry: the five monitor kinds

Open Settings › Monitors, click + (New Monitor) and choose Sentry. Pick a kind, or start from an example. Test runs the query once, saves nothing and shows the issues that match now.

In today’s Sentry, every monitor type opens an issue when it trips: an error, a cron check-in that fails or is missed, an uptime check that fails, a metric monitor that crosses its threshold. Sentry resolves the issue on recovery and marks it regressed when it trips again. So four kinds are views of one issue search, and CoIsland alerts exactly when Sentry’s own thresholds say so.

Kind	What you write	What alerts
Issue search	Any Sentry search	An issue that starts matching
Regressed & escalating	Projects, environments, the two states	An issue that came back after being resolved, or whose volume beats Sentry’s forecast
Assigned to me	Projects, environments, suggested owners or not	An issue assigned (or suggested) to you
Crons, uptime & metric	Projects, environments, which monitors	A cron, uptime or metric monitor’s issue opening or regressing
New releases	One or more projects, environments	A release created in the last 30 days

Every kind takes two words of CoIsland’s own, sent to Sentry as filters: project:slug and environment:name, each as often as you like. No project means every project the token can see. The rest is Sentry’s search syntax, as you type it in Sentry’s Issues page.

Issue search

is:unresolved level:error firstSeen:-24h
environment:production is:unresolved level:fatal
project:checkout is:unresolved error.unhandled:true

An empty search is is:unresolved, Sentry’s own default. An issue resolved and back between two checks never left the result, so it does not alert here; Regressed & escalating catches it.

Regressed and escalating

environment:production is:regressed is:escalating

Sentry’s issue search cannot join two is: words with OR, so CoIsland asks once per state and merges the answers.

Assigned to me

assigned:me is:unresolved
assigned_or_suggested:me is:unresolved

The second includes issues Sentry’s ownership rules and suspect commits suggest for you; the notch card says Suggested on those. An issue unassigned, then assigned to you again, alerts again.

Crons, uptime and metric monitors

project:billing is:unresolved issue.type:[monitor_check_in_failure,uptime_domain_failure,metric_issue]

The card reads like a status page: Down, Regressed or Resolved, then Cron, Uptime or Metric, then the number of failures.

New releases

project:checkout environment:production

A release alerts once, when it appears; the card shows how many new issues it brought.

A Sentry monitor is a watch file

Every monitor is a .sql file in ~/.coisland/watches. This is checkout-outages.sql:

-- name: Checkout outages
-- kind: sentry.outages
-- connector: acme
-- every: 5m
-- alert: new-rows
-- title: {SHORT_ID} {TITLE}

project:checkout environment:production is:unresolved issue.type:[monitor_check_in_failure,uptime_domain_failure]

-- kind:	Monitor kind
sentry.issues	Issue search
sentry.regressions	Regressed & escalating
sentry.assigned	Assigned to me
sentry.outages	Crons, uptime & metric
sentry.releases	New releases

Changing the projects, the search or the connector starts a fresh baseline. Watch files lists every header key.

What a Sentry alert shows

A click on the notch opens the alert in CoIsland. Each issue is a card that fills in live from Sentry: short ID, title and state, level, events, users, first seen, releases, environment and culprit, then the latest event: every exception of the chain, your app’s own frames with the line that failed, every frame in a collapsed block, and every tag. Breadcrumbs, request bodies and local variables are never read. Open in Sentry goes to the issue. A release card shows its commits, deploys and new issues.

Rate limits and how often to check

Sentry limits how often a token may call each endpoint, and asks integrations not to poll hard. One check is one request for 100 issues, more only when more match, up to 1,000. Check every minute or more; every 5 minutes suits most monitors. When Sentry’s rate limit runs out in the middle of a check, CoIsland stops, compares nothing, and says “Sentry’s rate limit was reached; the next check tries again.”

Self-hosted Sentry

Enter your Sentry’s address, with its path if it has one. It must be https://: http:// is refused with “Use https: the token is only ever sent over an encrypted connection.” The token goes to that address only, and CoIsland follows no redirect. A certificate from your company’s own authority must be trusted by your Mac: “The certificate of sentry.example.com is not trusted by this Mac. Add your company’s root certificate to Keychain Access.”

Troubleshooting Sentry connector errors

• “The token was refused. Check it has not expired or been revoked.” Sentry answered 401. Create a new token and add it as a new connector.
• “Not allowed: …; it needs Read on Organization, Project and Issue & Event, or your organization may not allow personal tokens (ask an owner).” A 403: a missing scope, or an organization that limits personal tokens.
• “Organization acme is not visible to this token. It sees: …” The slug is wrong, or you are not a member.
• “Sentry refused the search: …” Sentry rejected the query (400) and CoIsland quotes its reason.
• “This issue was merged into another one. Open it in Sentry.” The saved link still works on the site.
• “Rate limited; retry after …” The next check tries again.

Next steps

• Getting started walks through your first alert, and Agents hands one to Claude Code, Codex or Cortex Code.
• The Sentry connector page sums up what CoIsland watches in Sentry.