Connect PagerDuty

To connect PagerDuty to CoIsland you need one thing: an API User Token from your own PagerDuty profile. No admin, no app to register, no OAuth. CoIsland calls PagerDuty’s REST API straight from your Mac, with no CoIsland server or account in between, keeps the token in your login Keychain, and only ever reads. This page covers the token, the connector form, the six PagerDuty monitor kinds with queries you can paste, and the errors you may meet.

Create a PagerDuty API User Token

1. Sign in to PagerDuty at https://your-subdomain.pagerduty.com, or https://your-subdomain.eu.pagerduty.com for an account in the EU region.
2. Select your user icon at the top right, then My Profile, then the User Settings tab.
3. Under API Access, select Create API User Token.
4. Enter a description, such as CoIsland, then select Create Key.
5. Copy the key now: PagerDuty shows it in full only this once. If you lose it, delete it and create another.

The token acts as you, with your permissions: CoIsland sees the incidents, services, teams and schedules you can see in PagerDuty, and nothing more. On accounts with Advanced Permissions, the Restricted Access, Observer, Responder and Manager roles can create one; Stakeholders cannot. Do not use an account-wide (general access) key: CoIsland needs to know who “me” is, and those keys belong to no user.

Connect PagerDuty in CoIsland

Open Settings › Connectors, click + at the top right (or Add Connector when you have none yet), and choose PagerDuty.

Field	What to enter
Connector name	What monitors call it: pagerduty, or your subdomain once tested. Letters, digits, _ and -.
User API token	The token you created.

Then click Test connector, which saves nothing. It calls GET /users/me on api.pagerduty.com and, if the US region refuses the token, once more on api.eu.pagerduty.com. A success reads Connected, with your name, email, account address, region and role. There is no region field to get wrong: your account’s address says whether it is in the US or the EU region.

Click Add Connector. The name, the region and the account address go to ~/Library/Application Support/CoIsland/connectors.json, the token to your login Keychain. The token is only ever sent to https://api.pagerduty.com or https://api.eu.pagerduty.com, in the Authorization header, whatever that file says. The first PagerDuty connector becomes the default.

Choose what to watch: the six PagerDuty monitor kinds

Open Monitors, add a monitor and choose PagerDuty. Each kind is a few key:value words, written for you by the editor’s fields: services, teams, escalation policies and schedules are picked by name and saved as IDs. The examples check every minute; a new monitor checks every 15 minutes unless you choose otherwise, from 30 seconds up. A new-items monitor’s first check records what is already there and raises nothing.

Assigned to me

An open incident alerts when it is assigned to you, and again when it comes back to you by escalation or reassignment: each assignment has its own time.

status:triggered,acknowledged urgency:high

Incidents

A matching incident alerts once, when it first appears. Pick services, teams (team:mine is your teams, read at each check) or scope:all for every incident you can see. Resolved incidents, when asked for, are those of the last 24 hours.

team:mine status:triggered

With the rule Count crosses a threshold set to more than 10, the same query is an incident storm alert.

Status changes

The same incident alerts each time it is in a status it was not in at the last check: triggered, acknowledged, resolved. Incidents of the last 24 hours.

team:mine

Acknowledged too long

An acknowledged incident alerts once when it has sat acknowledged for longer than older:, from 5 minutes to 24 hours. A new acknowledgement starts the clock again.

older:30m team:mine

On call now

Your current on-call shifts are the rows: a shift that starts alerts, and the notch card reads “On call until Fri 09:00”. With Count crosses a threshold set to equals 0, CoIsland tells you when you go off call instead. Narrow it with policy: or schedule:.

user:me

Shift starting soon

One of your shifts alerts once when it starts within within:, from 5 minutes to 7 days, which must be longer than the check interval.

within:1h

Click Test to run the query once: nothing is saved or alerted. A check reads up to 1,000 incidents; when more match, nothing new is compared and the monitor asks you to narrow it, while a count rule still fires.

What a PagerDuty alert shows

The notch lists each incident as Checkout API #1234 · Triggered · High · you: where, how bad, who has it. Clicking it opens the alert in CoIsland. The incident’s card fills in live: assignees, urgency, priority, service, escalation policy, teams, alert counts, the conference bridge, the first alert’s details as a table, and a Timeline of notes and log entries with the one the alert is about first. Open in PagerDuty goes to the incident. A shift’s card says who is on call beside you, who is next, or who hands over to you.

What a PagerDuty monitor’s watch file looks like

-- name: Triggered on my teams
-- kind: pagerduty.incidents
-- connector: pagerduty
-- every: 1m
-- alert: new-rows
-- sound: Glass

team:mine status:triggered

The kinds are pagerduty.assigned, pagerduty.incidents, pagerduty.status, pagerduty.stale-acks, pagerduty.oncall-now and pagerduty.oncall-next. Changing the query, the kind or the connector starts a new baseline. Watch files lists every header key.

Rate limits

PagerDuty allows 960 REST requests a minute per user, shared by all of that user’s keys. A check costs one request per 100 incidents, plus a read of who you are every ten minutes; six monitors checking every minute use about 1% of it. If you also run other PagerDuty tools as yourself, they share the same limit. When PagerDuty asks CoIsland to slow down, checks back off on their own.

Troubleshooting PagerDuty connector errors

• The token was refused. Check it has not expired or been revoked. Create a new API User Token under My Profile › User Settings. PagerDuty answered 401: the token was mistyped, you deleted it, your user was removed, or an account Owner or Admin deleted it (they can delete other users’ personal keys). Create a new token, add it as a new connector, and pick that connector under Runs on in each monitor.
• Not allowed. The token may lack a permission. PagerDuty answered 403: your role was lowered, or you can no longer see a service or team the monitor names.
• Your PagerDuty plan does not include team or urgency filters. Remove them. PagerDuty answered 402: your plan lacks the teams or urgencies ability. The editor hides those fields when your plan lacks them.
• PagerDuty refused the request: then PagerDuty’s reasons, for a request it found invalid.
• Rate limited; retry after 51s. PagerDuty answered 429. The next check tries again.
• Pick a service or a team, or choose all incidents. An Incidents, Status changes or Acknowledged too long monitor needs service:, team: or scope:all.
• team:mine: you are on no PagerDuty team. Pick services or teams by name instead.
• This incident no longer exists in PagerDuty (merged or deleted). The saved copy is shown. The alert keeps the incident as it was.
• No PagerDuty connector is named acme. A monitor’s -- connector: line names a connector that does not exist.

Common questions

Does CoIsland need PagerDuty admin rights?

No. Any user who can create an API User Token under their own profile can connect: Responders, Managers, Observers and Restricted Access users on Advanced Permissions accounts.

Can CoIsland acknowledge or resolve incidents?

No. It only reads. Acknowledge and resolve in PagerDuty, from the incident Open in PagerDuty opens.

Does it work with a PagerDuty account in the EU region?

Yes. CoIsland reads the region from your account when you test the connector, and calls api.eu.pagerduty.com from then on.

Next: Getting started for the rest of the app, or the PagerDuty connector for everything it can watch.