# Connect Sentry

> Monitor Sentry with the searches you already write. New errors, regressions, issues assigned to you, failing crons, sites down and new releases reach your Mac's notch, from sentry.io or your own Sentry.

Source: https://coisland.app/docs/connect-sentry/

## What you need

- **You need:** Personal token, Read scopes, from User settings › Personal Tokens
- **The form asks:** Sentry address, Organization, Connector name, Personal token
- **You can watch:** Issue search, Regressed & escalating, Assigned to me, Crons, uptime & metric, New releases
- **Access:** GET requests only, with Read scopes; it never resolves, assigns or mutes

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

```text
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

```text
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

```text
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

```text
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

```text
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`:

```text
-- 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](https://coisland.app/docs/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](https://coisland.app/docs/getting-started/) walks through your first alert, and [Agents](https://coisland.app/docs/agents/) hands one to Claude Code, Codex or Cortex Code.
- The [Sentry connector page](https://coisland.app/sentry/) sums up what CoIsland watches in Sentry.