Escalate incident in PagerDuty

Overview

This self service guide provides a comprehensive walkthrough on how to escalate incident in Pagerduty from Port using Port's self service actions.

Prerequisites

1. Port's GitHub app needs to be installed.

2. In your GitHub repository, go to Settings > Secrets and add the following secrets:

   • PAGERDUTY_API_KEY - PagerDuty API token generated by the user.
   • PORT_CLIENT_ID - Your port client id How to get the credentials.
   • PORT_CLIENT_SECRET - Your port client secret How to get the credentials.

3. Optional - Install Port's PagerDuty integration learn more

   PagerDuty Integration

   This step is not required for this example, but it will create all the blueprint boilerplate for you, and also ingest and update the catalog in real time with your PagerDuty Incidents.

4. In Case you decided not to install the PagerDuty integration, you will need to create a blueprint for PagerDuty incidents in Port.

PagerDuty Incident Blueprint

{
  "identifier": "pagerdutyIncident",
  "description": "This blueprint represents a PagerDuty incident in our software catalog",
  "title": "PagerDuty Incident",
  "icon": "pagerduty",
  "schema": {
    "properties": {
      "status": {
        "type": "string",
        "title": "Incident Status",
        "enum": [
          "triggered",
          "annotated",
          "acknowledged",
          "reassigned",
          "escalated",
          "reopened",
          "resolved"
        ]
      },
      "url": {
        "type": "string",
        "format": "url",
        "title": "Incident URL"
      },
      "urgency": {
        "type": "string",
        "title": "Incident Urgency",
        "enum": ["high", "low"]
      },
      "responder": {
        "type": "string",
        "title": "Assignee"
      },
      "escalation_policy": {
        "type": "string",
        "title": "Escalation Policy"
      },
      "created_at": {
        "title": "Create At",
        "type": "string",
        "format": "date-time"
      },
      "updated_at": {
        "title": "Updated At",
        "type": "string",
        "format": "date-time"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {
    "pagerdutyService": {
      "title": "PagerDuty Service",
      "target": "pagerdutyService",
      "required": false,
      "many": true
    }
  }
}

GitHub Workflow

Create the file .github/workflows/escalate-incident.yaml in the .github/workflows folder of your repository.

tip

We recommend creating a dedicated repository for the workflows that are used by Port actions.

GitHub Workflow

escalate-incident.yaml

name: Escalate PagerDuty Incident

on:
  workflow_dispatch:
    inputs:
      escalation_policy_id:
        description: PagerDuty Escalation Policy ID to apply
        required: true
        type: string
      urgency:
        description: New urgency level for the incident (e.g., "high")
        required: false
        type: string
      from:
        description: The email address of a valid user associated with the account making the request.
        required: true
        type: string
      port_payload:
        required: true
        description: >-
          Port's payload, including details for who triggered the action and
          general context (blueprint, run id, etc...)

jobs:
  escalate-incident:
    runs-on: ubuntu-latest
    steps:
      - name: Inform execution of request to escalate incident
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.getport.io
          operation: PATCH_RUN
          runId: ${{fromJson(github.event.inputs.port_payload).context.runId}}
          logMessage: "About to escalate incident in PagerDuty..."

      - name: Escalate Incident in PagerDuty
        id: escalate_incident
        uses: fjogeleit/http-request-action@v1
        with:
          url: 'https://api.pagerduty.com/incidents/${{fromJson(github.event.inputs.port_payload).context.entity}}'
          method: 'PUT'
          customHeaders: '{"Content-Type": "application/json", "Accept": "application/vnd.pagerduty+json;version=2", "Authorization": "Token token=${{ secrets.PAGERDUTY_API_KEY }}", "From": "${{ github.event.inputs.from }}"}'
          data: >-
            {
              "incident": {
                "type": "incident_reference",
                "escalation_policy": {
                  "id": "${{ github.event.inputs.escalation_policy_id }}",
                  "type": "escalation_policy_reference"
                },
                "urgency": "${{ github.event.inputs.urgency }}"
              }
            }

      - name: Inform PagerDuty request failure
        if: failure()
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.getport.io
          operation: PATCH_RUN
          runId: ${{fromJson(github.event.inputs.port_payload).context.runId}}
          logMessage: "Request to escalate incident failed ..."

      - name: Inform ingestion of PagerDuty escalation to Port
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.getport.io
          operation: PATCH_RUN
          runId: ${{fromJson(github.event.inputs.port_payload).context.runId}}
          logMessage: "Reporting the escalated incident back to Port ..."

      - name: Upsert pagerduty entity to Port 
        uses: port-labs/port-github-action@v1
        with:
          identifier: ${{fromJson(github.event.inputs.port_payload).context.entity}}
          title: "${{ fromJson(steps.escalate_incident.outputs.response).incident.title }}"
          blueprint: "pagerdutyIncident"
          properties: |-
            {
              "status": "${{ fromJson(steps.escalate_incident.outputs.response).incident.status }}",
              "url": "${{ fromJson(steps.escalate_incident.outputs.response).incident.self }}",
              "urgency": "${{ fromJson(steps.escalate_incident.outputs.response).incident.urgency }}",
              "responder": "${{ fromJson(steps.escalate_incident.outputs.response).incident.assignments[0].assignee.summary}}",
              "escalation_policy": "${{ fromJson(steps.escalate_incident.outputs.response).incident.escalation_policy.summary }}",
              "created_at": "${{ fromJson(steps.escalate_incident.outputs.response).incident.created_at }}",
              "updated_at": "${{ fromJson(steps.escalate_incident.outputs.response).incident.updated_at }}"
            }
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.getport.io
          operation: UPSERT
          runId: ${{ fromJson(inputs.port_payload).context.runId }}

      - name: Inform Entity upsert failure
        if: failure()
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.getport.io
          operation: PATCH_RUN
          runId: ${{fromJson(github.event.inputs.port_payload).context.runId}}
          logMessage: "Failed to report the escalated incident back to Port ..."

      - name: Inform completion of PagerDuty escalation process into Port
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.getport.io
          operation: PATCH_RUN
          runId: ${{fromJson(github.event.inputs.port_payload).context.runId}}
          logMessage: "Incident escalation process was successful ✅"

Port Configuration

Create a new self service action using the following JSON configuration.

Escalate Incident In PagerDuty (click to expand)

Modification Required

Make sure to replace <GITHUB_ORG> and <GITHUB_REPO> with your GitHub organization and repository names respectively.

{
  "identifier": "pagerdutyIncident_escalate_incident",
  "title": "Escalate Incident",
  "icon": "pagerduty",
  "description": "Escalate a pagerduty incident",
  "trigger": {
    "type": "self-service",
    "operation": "DAY-2",
    "userInputs": {
      "properties": {
        "escalation_policy_id": {
          "title": "Escalation Policy ID",
          "description": "PagerDuty Escalation Policy ID to apply",
          "icon": "pagerduty",
          "type": "string"
        },
        "urgency": {
          "icon": "pagerduty",
          "title": "Urgency",
          "description": "New urgency level for the incident (e.g., \"high\")",
          "type": "string",
          "default": "low",
          "enum": [
            "high",
            "low"
          ],
          "enumColors": {
            "high": "orange",
            "low": "lightGray"
          }
        },
        "from": {
          "icon": "User",
          "title": "From",
          "description": "The email address of a valid pagerduty user associated with the account making the request.",
          "type": "string",
          "format": "user"
        }
      },
      "required": [
        "escalation_policy_id",
        "urgency",
        "from"
      ],
      "order": [
        "escalation_policy_id",
        "urgency",
        "from"
      ]
    },
    "blueprintIdentifier": "pagerdutyIncident"
  },
  "invocationMethod": {
    "type": "GITHUB",
    "org": "<GITHUB_ORG>",
    "repo": "<GITHUB_REPO>",
    "workflow": "ecalate-an-incident.yaml",
    "workflowInputs": {
      "{{if (.inputs | has(\"ref\")) then \"ref\" else null end}}": "{{.inputs.\"ref\"}}",
      "{{if (.inputs | has(\"escalation_policy_id\")) then \"escalation_policy_id\" else null end}}": "{{.inputs.\"escalation_policy_id\"}}",
      "{{if (.inputs | has(\"urgency\")) then \"urgency\" else null end}}": "{{.inputs.\"urgency\"}}",
      "{{if (.inputs | has(\"from\")) then \"from\" else null end}}": "{{.inputs.\"from\"}}",
      "port_payload": {
        "action": "{{ .action.identifier[(\"pagerdutyIncident_\" | length):] }}",
        "resourceType": "run",
        "status": "TRIGGERED",
        "trigger": "{{ .trigger | {by, origin, at} }}",
        "context": {
          "entity": "{{.entity.identifier}}",
          "blueprint": "{{.action.blueprint}}",
          "runId": "{{.run.id}}"
        },
        "payload": {
          "entity": "{{ (if .entity == {} then null else .entity end) }}",
          "action": {
            "invocationMethod": {
              "type": "GITHUB",
              "org": "<GITHUB_ORG>",
              "repo": "<GITHUB_REPO>",
              "workflow": "ecalate-an-incident.yaml",
              "omitUserInputs": false,
              "omitPayload": false,
              "reportWorkflowStatus": true
            },
            "trigger": "{{.trigger.operation}}"
          },
          "properties": {
            "{{if (.inputs | has(\"escalation_policy_id\")) then \"escalation_policy_id\" else null end}}": "{{.inputs.\"escalation_policy_id\"}}",
            "{{if (.inputs | has(\"urgency\")) then \"urgency\" else null end}}": "{{.inputs.\"urgency\"}}",
            "{{if (.inputs | has(\"from\")) then \"from\" else null end}}": "{{.inputs.\"from\"}}"
          },
          "censoredProperties": "{{.action.encryptedProperties}}"
        }
      }
    },
    "reportWorkflowStatus": true
  },
  "requiredApproval": false,
  "publish": true
}

Now you should see the Escalate Incidents action in the self-service page. 🎉

Let's test it!

1. Head to the Self Service hub
2. Click on the Escalate Incident action
3. Choose the pagerduty incident you want to escalate (In case you didn't install the PagerDuty integration, it means you don't have any PagerDuty incidents in Port yet, so you will need to create one manually in Port to test this action)
4. Select the new incident
5. Enter the Escalation Policy ID, Urgency and From (email address of a valid pagerduty user associated with the account making the request).
6. Click on Execute
7. Done! wait for the incident's status to be changed in PagerDuty.

Congrats 🎉 You've escalated a PagerDuty incident in Port 🔥

More Self Service PagerDuty Actions Examples

• Acknowledge Incident
• Change On-Call User
• Change PagerDuty incident owner
• Create PagerDuty incident
• Create PagerDuty service
• Resolve an incident
• Trigger PagerDuty incident