PagerDuty connector
Mirror the incidents of selected PagerDuty services into a Workspace.
The PagerDuty connector mirrors the incidents of selected services into a Workspace repository. ctxpipe requests read access and the permission to create its webhook subscription. It does not acknowledge or resolve incidents, and it does not show live on-call state.
After you authorize an account, ctxpipe creates one signed webhook subscription for the connection. On a self-hosted deployment, the operator registers a PagerDuty OAuth app first. See Self-host PagerDuty.
What is mirrored
ctxpipe syncs the incidents of each selected service from the last 90 days. Each incident is one Markdown file with:
- the title, status, urgency, service, assignees, and times;
- the body of the alert that started it, with its details, such as a host name;
- a short list of the other alerts on the incident;
- the incident notes;
- image attachments, copied next to the file.
ctxpipe removes routing keys and other secret alert fields before it writes to git. If an incident moves to a service that is not selected, ctxpipe deletes its file.
Connect PagerDuty
Follow Add a tool to a Workspace. For PagerDuty:
- On Connectors, select Add connection, then select Connect on the PagerDuty row. Authorize the app in the PagerDuty popup.
- In Add to Workspaces, select the Workspaces, then the services. If the list is empty, create a service in PagerDuty first.
- Merge the pull request that adds
sources/pagerduty/<name>.md.
Source file
---
provider: pagerduty
connection: con_example
services: [PSVC001, PSVC002]
---Files in the repository
pagerduty/services/<serviceId>/incidents/<number>--<id>.md
pagerduty/services/<serviceId>/incidents/<number>--<id>/assets/…When you remove a service from the scope, the next sync deletes the incident files of that service.
How incidents stay current
PagerDuty sends a signed event when an incident changes, or when a new alert arrives on it. The subscription covers the whole account, but ctxpipe fetches and writes only the incidents of the services in a Connected source. It ignores the other events.
Check the setup
- The PagerDuty account shows on Connectors.
- After the merge, the Workspace repository has files under
pagerduty/services/. - When you trigger or update an incident of a selected service, its file changes. This step tests the webhook.
Troubleshooting
- Changes do not arrive. Make sure that the incident is on a selected
service. Then ask the operator to check that the connection still has its
webhook subscription, and that
POST /api/v1/webhook/pagerdutyis reachable. - You reconnect PagerDuty. ctxpipe keeps or replaces the webhook subscription. It never adds a second one.
- You remove the connector. ctxpipe also deletes the webhook subscription in PagerDuty.
For other problems, see Troubleshooting.