@render-lab/tasks-pagerduty

⚠️ Experimental: proof of concept. This package is part of the Render Tasks POC and is published for testing only. It is not fully tested or production ready. Task names, inputs, outputs, and behavior can change or break in any release. Pin exact versions and expect breaking changes.

Durable PagerDuty tasks for Render Workflows.

import {
  trigger,
  acknowledge,
  resolve,
  addNote,
  listIncidents,
  getIncident,
  assignIncident,
  listOnCall,
  snooze,
} from "@render-lab/tasks-pagerduty";

| Task | Input | Output | Transport | | ------------------------- | ----------------------------------------------------------- | ---------------------------- | -------------- | | pagerduty.trigger | { summary, source, severity?, dedupKey?, details? } | { dedupKey, status } | Events API v2 | | pagerduty.acknowledge | { dedupKey } | { dedupKey, status } | Events API v2 | | pagerduty.resolve | { dedupKey } | { dedupKey, status } | Events API v2 | | pagerduty.addNote | { incidentId, note } | { incidentId, noteId } | REST API | | pagerduty.listIncidents | { statuses?, urgency?, limit? } | Incident[] | REST API | | pagerduty.getIncident | { incidentId } | Incident | REST API | | pagerduty.assignIncident| { incidentId, assigneeId } | Incident | REST API (write) | | pagerduty.listOnCall | { scheduleIds?, limit? } | OnCall[] | REST API | | pagerduty.snooze | { incidentId, duration } | Incident | REST API (write) |

trigger opens (or deduplicates onto) an incident through the PagerDuty Events API v2. severity defaults to "error" ("critical" | "error" | "warning" | "info"). Pass a dedupKey to make triggers idempotent and to correlate later acknowledge / resolve calls — PagerDuty generates one and returns it when omitted. details is attached as custom_details.

addNote uses the PagerDuty REST API to append a note to an existing incident (POST /incidents/{id}/notes).

The remaining REST tasks operate on incidents and schedules:

• listIncidents (GET /incidents) lists incidents, filtered by statuses ("triggered" | "acknowledged" | "resolved") and urgency ("high" | "low"). Each result is an Incident DTO { id, title, status, urgency, createdAt, htmlUrl }.
• getIncident (GET /incidents/{id}) fetches one incident as an Incident DTO.
• assignIncident (PUT /incidents/{id}) reassigns an incident to assigneeId (a user id) and returns the updated Incident.
• listOnCall (GET /oncalls) returns who is currently on call as OnCall DTOs { user: { id, summary }, schedule: { id, summary }, escalationLevel }, optionally filtered by scheduleIds.
• snooze (POST /incidents/{id}/snooze) snoozes an incident for duration seconds and returns the updated Incident.

Write requests need a From header. PagerDuty requires REST writes that act on a user's behalf (assignIncident, snooze) to carry a From: <email> header identifying an account user. This package reads it lazily from the PAGERDUTY_FROM_EMAIL env var and sends it automatically; the read tasks never require it.

Each task ships the PD_RETRY policy (4 retries, exponential backoff over ~1s/2s/4s/8s). A non-2xx response throws so the durable task retry handles transient failures — vendor retries are off.

Install

pnpm add @render-lab/tasks-pagerduty @renderinc/sdk

@renderinc/sdk is a peer dependency. This package has no vendor SDK — it calls PagerDuty (Events API v2 and REST) with the built-in fetch.

Environment contract

Credentials are read lazily on first use (never at import), so importing the package for the Events tasks does not require the REST token, and vice versa. A missing credential throws a clear, named error from the task that needs it.

| Variable | Required | Purpose | | ----------------------- | ------------------------------- | ----------------------------------------------------------------------- | | PAGERDUTY_ROUTING_KEY | required for Events API tasks | Integration routing key for trigger, acknowledge, resolve. | | PAGERDUTY_API_TOKEN | required for the REST tasks | REST API token, sent as Authorization: Token token=… (all REST tasks).| | PAGERDUTY_FROM_EMAIL | required for REST write tasks | Account user email sent as the From header for assignIncident / snooze. |

Extending & testing

Every task exports its raw *Impl, which depends on a PagerDutyPort. pagerDutyHttpPort accepts an injected fetchImpl and env, so both the impls and the transport unit-test without network access:

import { triggerImpl } from "@render-lab/tasks-pagerduty";

const res = await triggerImpl(
  { summary: "DB down", source: "sentry", dedupKey: "err-42" },
  { pagerduty: { enqueue: async (_a, p) => ({ dedupKey: p.dedupKey!, status: "success" }), addNote: async () => ({ noteId: "PN1" }) } },
);
// res.dedupKey === "err-42", severity defaulted to "error"

Run the tests with pnpm -C packages/tasks-pagerduty test.