PagerDuty

The PagerDuty plugin lets formae manage PagerDuty on-call infrastructure as code: users, contact methods, notification rules, teams and memberships, schedules and overrides, escalation policies, services, integrations, and maintenance windows.

Repository: formae-plugin-pagerduty

Installation

git clone https://github.com/platform-engineering-labs/formae-plugin-pagerduty.git
cd formae-plugin-pagerduty
make install

This builds the plugin and installs it to ~/.pel/formae/plugins/pagerduty/. The formae agent discovers installed plugins automatically on startup. Requires Go 1.26+.

Configuration

Target

Configure a PagerDuty target in your Forma file:

import "@formae/formae.pkl"
import "@pagerduty/pagerduty.pkl"

target: formae.Target = new formae.Target {
    label = "my-pagerduty"
    namespace = "PAGERDUTY"
    config = new pagerduty.Config {
        subdomain = "your-subdomain"          // immutable; identifies the PagerDuty account
        fromEmail = "oncall@your-domain.com"  // optional; used as the From header where PagerDuty requires it
    }
}

The target config carries no credentials. It only identifies which PagerDuty account this target represents. The API token is resolved separately, at operation time.

Credentials

The plugin resolves a PagerDuty REST API token from the following sources, in order:

  1. The PAGERDUTY_TOKEN environment variable
  2. The file ~/.config/pagerduty/token (single line)

Set the environment variable before applying:

export PAGERDUTY_TOKEN="your-api-token"

Create a General Access REST API key under Integrations > API Access Keys > Create New API Key in the PagerDuty UI, and leave "Read-only" unchecked so the plugin can create and update resources. The token is read fresh on each client construction and is never persisted to the formae datastore.

Examples

The plugin repo ships several examples. Clone the repo and resolve Pkl dependencies before running one:

git clone https://github.com/platform-engineering-labs/formae-plugin-pagerduty.git
cd formae-plugin-pagerduty
pkl project resolve examples/users-and-teams

Then apply it:

# Set credentials
export PAGERDUTY_TOKEN="your-api-token"

# Evaluate the forma
formae eval examples/users-and-teams/main.pkl

# Apply resources
formae apply --mode reconcile --watch examples/users-and-teams/main.pkl

The repo includes four examples:

Example What it shows
users-and-teams Minimal starting point: a user and a team
schedule-restrictions A multi-layer schedule using both daily and weekly layer restrictions
grafana-integration Cross-plugin demo: a Grafana contact point paging a PagerDuty service through an integration key
datadog-integration Cross-plugin demo: a Datadog monitor paging a PagerDuty service

Supported Resources

Resource type Description
PAGERDUTY::Core::User PagerDuty user account, identified by email, with full create, read, update, and delete support
PAGERDUTY::Core::ContactMethod A user's email, phone, or SMS channel
PAGERDUTY::Core::NotificationRule Pages one of a user's contact methods at a given urgency, after a start delay
PAGERDUTY::Core::Team A logical grouping of users
PAGERDUTY::Core::TeamMembership Adds a user to a team with a role (observer, responder, or manager)
PAGERDUTY::Core::Schedule An on-call rotation with daily or weekly layer restrictions
PAGERDUTY::Core::ScheduleOverride Temporary on-call coverage for a window, such as a vacation or a swap. Replacing any field replaces the override
PAGERDUTY::Core::EscalationPolicy Ordered escalation rules with user or schedule targets
PAGERDUTY::Core::Service An alert routing endpoint that references an escalation policy
PAGERDUTY::Core::MaintenanceWindow Silences one or more services for a time range, for example during a deploy
PAGERDUTY::Core::Integration A service-scoped event integration. Exposes its integration key as a resolvable so observability plugins such as Grafana and Datadog can wire alert sinks to a PagerDuty service in code

What's next

Release notes

See release notes for changes per version.