PagerDuty connector

Connect a PagerDuty account, review its Git-backed service scope, and keep selected incident context available to ctx|.

The PagerDuty connector mirrors selected incident context into a GitHub repository, then sends that repository through the normal ctx| ingestion pipeline. The generated pagerduty/config.yaml pull request makes the service scope reviewable before content sync begins.

ctx| requests read-only PagerDuty access plus webhook subscription permissions. It does not acknowledge, resolve, or otherwise write back to PagerDuty incidents, and it does not expose live on-call state.

Fully managed app flow

The hosted ctx| service supplies the PagerDuty OAuth application. After you authorize an account, ctx| creates one signed v3 webhook subscription for that connection. Self-hosted deployments that do not set a deployment OAuth app start with Register PagerDuty OAuth app in the wizard; paste the client id and secret there instead of restarting the deployment. See Self-host PagerDuty.

What is mirrored

You can select PagerDuty services that the authorized account can already see. For each in-scope incident, ctx| writes one Markdown file that can include:

Incident title, status, urgency, service, assignees, and timestamps.
The triggering alert body, including structured details such as a hostname.
A short list of additional alerts on that incident, with an overflow count when more exist.
Incident notes.
In-scope image attachments copied beside the incident file. Unsafe, signed, or failed downloads leave a PagerDuty permalink stub instead of a private URL.

PagerDuty v3 webhooks are incident events. Alert create or update arrives as incident.triggered or a later incident event. ctx| refetches the incident, alerts, and notes on each in-scope event rather than trusting the webhook envelope as the file contents.

Routing keys and other secret-bearing alert fields are stripped before Git write. Out-of-scope services produce no fetch and no file. If a live incident moves to an unscoped service, or PagerDuty returns 404, ctx| deletes that incident file.

Account webhooks, Git scope

The webhook subscription is account-level, so PagerDuty can deliver events for every service. ctx| only fetches and writes incidents whose service is listed in the live pagerduty/config.yaml.

Prerequisites

Permission to authorize an application in the PagerDuty account.
A ctx| GitHub connection with access to the destination repository.
Permission to merge the generated configuration pull request.

Configuration source of truth

PagerDuty scope exists only in pagerduty/config.yaml:

Draft scope is the YAML on the generated configuration pull request's branch.
Live scope is the YAML on the selected target branch after that pull request is merged.

ctx| does not keep a second draft or live scope outside Git. The connection tracks where content belongs and whether setup is complete; the merged YAML remains the source of truth for which services are approved.

Setup flow

Register the OAuth app (self-hosted only)

On a self-hosted deployment without a deployment OAuth app, choosing PagerDuty creates a draft connection and opens Register PagerDuty OAuth app. Follow the self-hosted PagerDuty guide to register the deployment app and save its credentials in ctx|. Hosted ctx| supplies its managed OAuth app and skips this step.

Connect PagerDuty

Open Connectors, choose Add connection, then select PagerDuty. Authorize the application in the PagerDuty popup.

Confirm GitHub

PagerDuty content is stored in Git before ingestion. If GitHub is not connected for this ctx| organization, complete the GitHub App installation first.

Choose a context repository

Select an existing connected repository. A dedicated private repository usually gives the clearest ownership and access boundary; create it in GitHub first, grant the ctx| GitHub App access, then refresh the repository list in ctx|.

Select services

Search and page through the account's services, then select at least one. If the list is empty, create a service in PagerDuty first and refresh. ctx| only reads existing services; it does not add PagerDuty integrations. Only incidents from the selected services are mirrored after the configuration pull request is merged.

Merge the configuration pull request

ctx| opens a pull request containing pagerduty/config.yaml. Review the selected services and repository audience, then merge it.

The pull request branch YAML is the draft. The target branch YAML becomes live only after merge; the setup dialog submits scope to that Git workflow rather than storing another copy.

Wait for initial sync and ingestion

After GitHub reports the merge, ctx| performs the first PagerDuty mirror and starts repository ingestion. The connector reaches Connected when the mirror succeeds. Repository indexing may continue afterwards; see Ingestion for the indexing lifecycle.

Files in the repository

Mirrored files live under pagerduty/:

pagerduty/config.yaml
pagerduty/incidents/<number>--<id>.md
pagerduty/incidents/<number>--<id>/assets/…

Do not hand-edit generated content. Change scope through Manage scope and review the replacement configuration pull request. Shrinking the live YAML prunes files for services that are no longer selected.

Keeping content current

PagerDuty sends signed webhook events to ctx| when incidents are created or updated. While the connector is live, ctx| verifies the HMAC against the raw body, skips the event unless the payload names a service that is in the live YAML, updates the affected file, and starts another repository ingestion.

Events that arrive before the connector is live, including during initial sync, are skipped rather than queued for later. Events for unscoped services are acknowledged and ignored. Stale deliveries are rejected. Missed webhook events are not automatically backfilled: repair webhook delivery, then update the affected incident in PagerDuty again so a fresh event is delivered, or use Retry content sync after a failed initial mirror.

Verify the complete flow

Complete PagerDuty OAuth and confirm the expected account appears.
Select a connected GitHub repository and at least one service.
Open and merge the generated pagerduty/config.yaml pull request.
Confirm the connector reaches Connected and the repository contains generated files under pagerduty/incidents/.
Trigger or update an in-scope incident in PagerDuty and confirm the matching Git file changes, including triggering-alert details and notes.
Confirm the destination repository reaches an indexed state in ctx|.

Steps 3 and 4 test the GitHub push webhook and initial mirror. Step 5 separately tests PagerDuty webhook delivery.

Troubleshooting

Authorization fails

Allow popups and retry. On fully managed ctx|, report persistent OAuth errors to support. On a self-hosted deployment, finish Register PagerDuty OAuth app in the wizard, or ask the operator to verify that a deployment OAuth app is configured, and that the callback URI matches exactly.

No pull request appears

Confirm that at least one service is selected and that the GitHub App has write access to the destination repository. Empty repositories are supported; ctx| initializes the default branch before opening the pull request. If setup reports that pull request creation failed, open the connector and choose Retry configuration pull request.

The connector stays on “Approve configuration”

The configuration pull request must be merged, not merely approved. Confirm that pagerduty/config.yaml reached the default branch and that GitHub webhooks for the ctx| GitHub App are healthy.

Content sync failed

Open the connector and choose Retry content sync. This retries the mirror without opening another configuration pull request. If it fails again, ask the operator to check worker logs, PagerDuty token refresh, GitHub write access, and outbound access to identity.pagerduty.com plus api.pagerduty.com or api.eu.pagerduty.com.

Changes in PagerDuty do not arrive

Initial sync can still succeed when later webhook delivery fails. Confirm the incident belongs to a live-scoped service. Out-of-scope events are ignored on purpose. Ask the operator to verify that the connection still has a webhook subscription and that POST /api/v1/webhook/pagerduty is reachable.

PagerDuty authorization was revoked

Open the existing connector and complete Connect PagerDuty again, or add PagerDuty once more for the same account. Incremental updates stop while the account authorization is revoked. Re-authorization keeps the existing subscription when its signing secret is still stored, and otherwise replaces it rather than stacking another one.

Removing the connector

Removing the connector deletes the PagerDuty webhook subscription while the access token is still available, then deletes the ctx| authorization and repository binding. It does not delete pagerduty/config.yaml, generated files, or Git history from the destination repository; remove those in GitHub if they are no longer required.

PagerDuty connector

On this page