ConnectionsSource connectors

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:

  1. On Connectors, select Add connection, then select Connect on the PagerDuty row. Authorize the app in the PagerDuty popup.
  2. In Add to Workspaces, select the Workspaces, then the services. If the list is empty, create a service in PagerDuty first.
  3. 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

  1. The PagerDuty account shows on Connectors.
  2. After the merge, the Workspace repository has files under pagerduty/services/.
  3. 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/pagerduty is 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.