# PagerDuty connector (https://docs.ctxpipe.ai/docs/connections/source-connectors/pagerduty)

The **PagerDuty connector** mirrors the incidents of selected services into a
[Workspace](/docs/workspaces) 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](/docs/self-hosting/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](/docs/connections#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

```markdown
---
provider: pagerduty
connection: con_example
services: [PSVC001, PSVC002]
---
```

## Files in the repository

```text
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](/docs/connections#troubleshooting).
