PagerDuty

PagerDuty integration actions allow workflows to create, acknowledge, and resolve incidents directly using your installed PagerDuty integration.

Prerequisites

• A PagerDuty integration installed in your Port organization.
• Actions processing must be enabled on your integration:
  • Hosted by Port / UI / OAuth installations: actions processing is enabled automatically.
  • Self-hosted (Helm or Docker): actions processing is disabled by default and must be explicitly enabled.
• A PagerDuty API token with write access to incidents on the services the workflow targets.
• Every action requires a fromEmail value: the email address of a valid PagerDuty user in your account. PagerDuty requires it on all write requests that are authenticated with an API token.

Configuration

All PagerDuty integration actions share the same node structure:

Field	Type	Description
type	string	Required. Must be "INTEGRATION_ACTION".
installationId	string	Required. Your PagerDuty integration installation ID.
integrationProvider	string	Required. Must be "pagerduty".
integrationInvocationType	enum	Required. One of the values listed in available actions.
integrationActionExecutionProperties	object	Required. Properties for the selected action.

Available actions

Each action is selected with the integrationInvocationType field:

Action	Invocation type	Description
Trigger an incident	trigger_incident	Create a new incident on a PagerDuty service
Acknowledge an incident	acknowledge_incident	Move an existing incident to the acknowledged status
Resolve an incident	resolve_incident	Move an existing incident to the resolved status, optionally adding a resolution note

The remaining sections describe the execution properties of each action.

Incident actions

Manage an incident

Create a new incident, or move an existing incident to the acknowledged or resolved status.

Completion is immediate

All three actions complete as soon as the PagerDuty API confirms the change. The node does not wait for the incident to be handled by a responder.

Trigger

Creates a new incident on a PagerDuty service. Set integrationInvocationType to "trigger_incident".

Execution properties

Field	Type	Description
service	string	Required. PagerDuty service ID to open the incident on.
title	string	Required. Incident title.
fromEmail	string	Required. Email of a valid PagerDuty user.
details	string	Incident body details.
urgency	string	Incident urgency: "high" or "low". Other values are rejected before the PagerDuty API is called.
incidentKey	string	Deduplication key. PagerDuty reuses an open incident on the same service that carries the same key instead of opening a second one.
escalationPolicyId	string	PagerDuty escalation policy ID to assign the incident to. Defaults to the service's own escalation policy.

Basic example

Trigger a PagerDuty incident (click to expand)

Open a high urgency incident on a service, using values collected by the workflow's trigger:

{
  "identifier": "trigger-pagerduty-incident",
  "title": "Trigger PagerDuty Incident",
  "config": {
    "type": "INTEGRATION_ACTION",
    "installationId": "your-installation-id",
    "integrationProvider": "pagerduty",
    "integrationInvocationType": "trigger_incident",
    "integrationActionExecutionProperties": {
      "service": "{{ .outputs.trigger.service }}",
      "title": "{{ .outputs.trigger.title }}",
      "fromEmail": "{{ .trigger.by.user.email }}",
      "details": "{{ .outputs.trigger.details }}",
      "urgency": "high"
    }
  }
}

Acknowledge

Moves an existing incident to the acknowledged status. Set integrationInvocationType to "acknowledge_incident".

Execution properties

Field	Type	Description
incidentId	string	Required. PagerDuty incident ID.
fromEmail	string	Required. Email of a valid PagerDuty user. The acknowledgement is attributed to this user in PagerDuty.

Basic example

Acknowledge a PagerDuty incident (click to expand)

Acknowledge the incident that triggered the workflow, on behalf of the user who ran it:

{
  "identifier": "acknowledge-pagerduty-incident",
  "title": "Acknowledge PagerDuty Incident",
  "config": {
    "type": "INTEGRATION_ACTION",
    "installationId": "your-installation-id",
    "integrationProvider": "pagerduty",
    "integrationInvocationType": "acknowledge_incident",
    "integrationActionExecutionProperties": {
      "incidentId": "{{ .outputs.trigger.incidentId }}",
      "fromEmail": "{{ .trigger.by.user.email }}"
    }
  }
}

Resolve

Moves an existing incident to the resolved status. Set integrationInvocationType to "resolve_incident".

Execution properties

Field	Type	Description
incidentId	string	Required. PagerDuty incident ID.
fromEmail	string	Required. Email of a valid PagerDuty user. The resolution is attributed to this user in PagerDuty.
resolution	string	Resolution note added to the incident's Notes tab in PagerDuty. Blank values are ignored.

The resolution note is best effort

Port resolves the incident first, then adds the note as a separate PagerDuty request. If the note fails, the incident stays resolved and the node still succeeds, with a run message stating that the note could not be added.

Basic example

Resolve a PagerDuty incident with a note (click to expand)

Resolve an incident and record why it was closed:

{
  "identifier": "resolve-pagerduty-incident",
  "title": "Resolve PagerDuty Incident",
  "config": {
    "type": "INTEGRATION_ACTION",
    "installationId": "your-installation-id",
    "integrationProvider": "pagerduty",
    "integrationInvocationType": "resolve_incident",
    "integrationActionExecutionProperties": {
      "incidentId": "{{ .outputs.trigger.incidentId }}",
      "fromEmail": "{{ .trigger.by.user.email }}",
      "resolution": "{{ .outputs.trigger.resolution }}"
    }
  }
}

Complete workflow examples

Placeholders

Replace all <...> placeholders (for example <your-installation-id>) with your actual values before using these workflows.

Report an incident from the service catalog (click to expand)

A self-service workflow that lets any member open a PagerDuty incident against a service, with the reporting user recorded as the incident's author:

{
  "identifier": "report-pagerduty-incident",
  "title": "Report a PagerDuty incident",
  "icon": "pagerduty",
  "description": "Open a PagerDuty incident on a service directly from Port.",
  "nodes": [
    {
      "identifier": "trigger",
      "title": "Report an incident",
      "icon": "pagerduty",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "userInputs": {
          "properties": {
            "service": {
              "title": "PagerDuty service",
              "type": "string",
              "format": "entity",
              "blueprint": "pagerdutyService"
            },
            "title": {
              "title": "Incident title",
              "type": "string"
            },
            "details": {
              "title": "Details",
              "type": "string",
              "format": "multi-line"
            },
            "urgency": {
              "title": "Urgency",
              "type": "string",
              "enum": ["high", "low"],
              "default": "high"
            }
          },
          "required": ["service", "title"],
          "order": ["service", "title", "details", "urgency"]
        },
        "actionCardButtonText": "Report",
        "executeActionButtonText": "Report",
        "published": true,
        "permissions": { "roles": ["Member", "Admin"] }
      }
    },
    {
      "identifier": "trigger_incident",
      "title": "Trigger PagerDuty incident",
      "icon": "pagerduty",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "<your-installation-id>",
        "integrationProvider": "pagerduty",
        "integrationInvocationType": "trigger_incident",
        "integrationActionExecutionProperties": {
          "service": "{{ .outputs.trigger.service }}",
          "title": "{{ .outputs.trigger.title }}",
          "details": "{{ .outputs.trigger.details }}",
          "urgency": "{{ .outputs.trigger.urgency }}",
          "fromEmail": "{{ .trigger.by.user.email }}"
        },
        "onFailure": "terminate"
      }
    }
  ],
  "connections": [
    {
      "sourceIdentifier": "trigger",
      "targetIdentifier": "trigger_incident"
    }
  ]
}

Acknowledge then resolve an incident (click to expand)

A self-service workflow that acknowledges an incident and resolves it in the same run, recording a resolution note:

{
  "identifier": "close-pagerduty-incident",
  "title": "Close a PagerDuty incident",
  "icon": "pagerduty",
  "description": "Acknowledge a PagerDuty incident and immediately resolve it with a note.",
  "nodes": [
    {
      "identifier": "trigger",
      "title": "Close an incident",
      "icon": "pagerduty",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "contexts": [
          {
            "on": "ENTITY",
            "userInput": "incident"
          }
        ],
        "userInputs": {
          "properties": {
            "incident": {
              "title": "PagerDuty incident",
              "type": "string",
              "format": "entity",
              "blueprint": "pagerdutyIncident"
            },
            "resolution": {
              "title": "Resolution note",
              "type": "string",
              "format": "multi-line"
            }
          },
          "required": ["incident", "resolution"],
          "order": ["incident", "resolution"]
        },
        "actionCardButtonText": "Close",
        "executeActionButtonText": "Close",
        "published": true,
        "permissions": { "roles": ["Member", "Admin"] }
      }
    },
    {
      "identifier": "acknowledge_incident",
      "title": "Acknowledge incident",
      "icon": "pagerduty",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "<your-installation-id>",
        "integrationProvider": "pagerduty",
        "integrationInvocationType": "acknowledge_incident",
        "integrationActionExecutionProperties": {
          "incidentId": "{{ .outputs.trigger.incident }}",
          "fromEmail": "{{ .trigger.by.user.email }}"
        },
        "onFailure": "terminate"
      }
    },
    {
      "identifier": "resolve_incident",
      "title": "Resolve incident",
      "icon": "pagerduty",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "<your-installation-id>",
        "integrationProvider": "pagerduty",
        "integrationInvocationType": "resolve_incident",
        "integrationActionExecutionProperties": {
          "incidentId": "{{ .outputs.trigger.incident }}",
          "fromEmail": "{{ .trigger.by.user.email }}",
          "resolution": "{{ .outputs.trigger.resolution }}"
        },
        "onFailure": "terminate"
      }
    }
  ],
  "connections": [
    {
      "sourceIdentifier": "trigger",
      "targetIdentifier": "acknowledge_incident"
    },
    {
      "sourceIdentifier": "acknowledge_incident",
      "targetIdentifier": "resolve_incident"
    }
  ]
}

Limitations

• Acknowledging or resolving an incident that is already in that status is rejected by PagerDuty, and the node fails with the error PagerDuty returns.
• Runs that target the same incident are executed one at a time, so two nodes cannot race on the same incident.
• When the PagerDuty API rate limit is close to being exhausted, Port pauses the integration's runs until the limit window resets.