docs(integrations): Opsgenie integrator reference

docs/content/issue_tracking/pro_integration/integrations.md

@@ -16,6 +16,7 @@ Supported Integrations:
 - GitHub
 - GitLab Boards
 - Jira
+- Opsgenie
 - PagerDuty
 - ServiceDesk Plus
 - ServiceNow
@@ -81,6 +82,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)
+- [Opsgenie](/issue_tracking/pro_integration/integrations_toolreference/#opsgenie)
 - [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)

docs/content/issue_tracking/pro_integration/integrations_toolreference.md

@@ -286,6 +286,47 @@ 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.
 
+## Opsgenie
+
+The Opsgenie Integration allows you to push DefectDojo Findings and Finding Groups as Opsgenie Alerts, optionally routed to an Opsgenie Team as a responder.
+
+### Instance Setup
+
+- **Label** should be the label that you want to use to identify this integration.
+- **Location** should be set to `https://api.opsgenie.com`.  If your Opsgenie account is hosted in the EU service region, use `https://api.eu.opsgenie.com` instead.  If your alerts live in Jira Service Management Operations (Atlassian is folding Opsgenie into JSM), use `https://api.atlassian.com/jsm/ops/integration`.
+- **API Key** should be set to an Opsgenie **API integration** key.  An account administrator can create one in the Opsgenie web app under **Settings > Integrations**: add an integration of type **API** and give it *Create and Update Access* (and *Read Access* so DefectDojo can verify the connection).  Note that this is an integration key, not a personal API key - DefectDojo authenticates with `GenieKey` authorization, which only integration keys support.
+
+### Issue Tracker Mapping
+
+- **Team Name** *(optional)* should be the name of the Opsgenie Team to add as a responder on created alerts.  You can leave it empty: if the API integration key is team-scoped, alerts route to that team automatically, and otherwise your account's own routing rules decide the responders.
+
+### Severity Mapping Details
+
+Severities map to the Opsgenie alert **Priority** field, which uses Opsgenie's fixed `P1` (critical) through `P5` (informational) scale:
+
+- **Severity Field Name**: `Priority`
+- **Info Mapping**: `P5`
+- **Low Mapping**: `P4`
+- **Medium Mapping**: `P3`
+- **High Mapping**: `P2`
+- **Critical Mapping**: `P1`
+
+If a severity is mapped to an unrecognized value, the priority is omitted and Opsgenie applies its own default (`P3`).
+
+### Status Mapping Details
+
+Opsgenie alerts are `open` or `closed`, and an open alert can additionally be `acknowledged`:
+
+- **Status Field Name**: `Status`
+- **Active Mapping**: `open`
+- **Closed Mapping**: `closed`
+- **False Positive Mapping**: `closed`
+- **Risk Accepted Mapping**: `acknowledged`
+
+Note that `closed` is a final status in Opsgenie - a closed alert cannot be reopened, and its alias is released.  Unlike some other tools, Opsgenie does allow content edits after creation, so pushing an updated Finding syncs its message, description, and priority alongside the status.
+
+DefectDojo sets each alert's **alias** to a stable key derived from the Finding or Finding Group, and Opsgenie de-duplicates open alerts by alias - so re-pushing the same Finding updates the existing open alert instead of creating a duplicate.
+
 ## PagerDuty
 
 The PagerDuty Integration allows you to push DefectDojo Findings and Finding Groups as PagerDuty Incidents, opened on a PagerDuty Service of your choice.