docs: add PagerDuty to the Pro Integrations tool reference

docs/content/issue_tracking/pro_integration/integrations.md

@@ -16,6 +16,7 @@ Supported Integrations:
 - GitHub
 - GitLab Boards
 - Jira
+- PagerDuty
 - ServiceDesk Plus
 - ServiceNow
 - Shortcut
@@ -80,6 +81,7 @@ For the complete list of requirements, please open the vendor specific pages bel
 - [GitHub](/issue_tracking/pro_integration/integrations_toolreference/#github)
 - [GitLab Boards](/issue_tracking/pro_integration/integrations_toolreference/#gitlab)
 - [Jira](/issue_tracking/pro_integration/integrations_toolreference/#jira)
+- [PagerDuty](/issue_tracking/pro_integration/integrations_toolreference/#pagerduty)
 - [ServiceDesk Plus](/issue_tracking/pro_integration/integrations_toolreference/#servicedesk-plus)
 - [ServiceNow](/issue_tracking/pro_integration/integrations_toolreference/#servicenow)
 - [Shortcut](/issue_tracking/pro_integration/integrations_toolreference/#shortcut)

docs/content/issue_tracking/pro_integration/integrations_toolreference.md

@@ -286,6 +286,46 @@ By default Jira issues use DefectDojo's built-in title and body. To customize th
 - **Token lifecycle (OAuth):** DefectDojo owns the whole flow — it performs the authorization-code exchange, stores the access and refresh tokens, and refreshes on demand before a push, persisting the new refresh token each time (Atlassian rotates it on every refresh).
 - **Credential storage:** all connection credentials (passwords, tokens, client secrets, OAuth tokens) are encrypted at rest and are never returned through the API — editing a connection shows a "leave blank to keep" placeholder for stored secrets.
 
+## PagerDuty
+
+The PagerDuty Integration allows you to push DefectDojo Findings and Finding Groups as PagerDuty Incidents, opened on a PagerDuty Service of your choice.
+
+### Instance Setup
+
+- **Label** should be the label that you want to use to identify this integration.
+- **Location** should be set to `https://api.pagerduty.com`.  If your PagerDuty account is hosted in the EU service region, use `https://api.eu.pagerduty.com` instead.
+- **API Token** should be set to a PagerDuty REST API key.  An account administrator can create one in the PagerDuty web app under **Integrations > API Access Keys > Create New API Key**.  Leave "Read-only" unchecked - DefectDojo needs to create and update incidents.
+- **From Email** should be the email address of a valid user on your PagerDuty account.  PagerDuty requires this address when creating or updating incidents, and it will be shown as the incident requester.
+
+### Issue Tracker Mapping
+
+- **Service ID** should be the ID of the PagerDuty Service that incidents will be opened on.  You can find it at the end of the URL while looking at the Service in PagerDuty, for example `https://{your-subdomain}.pagerduty.com/service-directory/{service id}`.
+
+### Severity Mapping Details
+
+By default this maps to the PagerDuty incident **Urgency** field, which only accepts `high` or `low`:
+
+- **Severity Field Name**: `Urgency`
+- **Info Mapping**: `low`
+- **Low Mapping**: `low`
+- **Medium Mapping**: `low`
+- **High Mapping**: `high`
+- **Critical Mapping**: `high`
+
+Alternatively, if your PagerDuty account has [Priorities](https://support.pagerduty.com/main/docs/incident-priority) enabled, you can map severities to Priority names instead.  Set the **Severity Field Name** to `Priority` and use your account's Priority names (for example `P1` through `P5`) as the mapping values.  When mapping to Priority, the incident's Urgency is left to your Service's own urgency rules.
+
+### Status Mapping Details
+
+PagerDuty incidents have three statuses: `triggered`, `acknowledged`, and `resolved`.
+
+- **Status Field Name**: `Status`
+- **Active Mapping**: `triggered`
+- **Closed Mapping**: `resolved`
+- **False Positive Mapping**: `resolved`
+- **Risk Accepted Mapping**: `acknowledged`
+
+Note that `resolved` is a final status in PagerDuty - a resolved incident cannot be reopened.  Also note that PagerDuty does not allow an incident's title or description to be edited after creation, so pushing an updated Finding will sync its status, urgency, and priority, but not content changes.
+
 ## ServiceNow
 
 The ServiceNow Integration allows you to push DefectDojo Findings as ServiceNow Incidents.