Trigger a PagerDuty Incident

Overview

This guide will help you implement a self-service action in Port that allows you to trigger PagerDuty incidents directly from Port. This functionality streamlines incident management by enabling users to trigger incidents without leaving Port.

You can implement this action in two ways:

1. GitHub workflow: A more flexible approach that allows for complex workflows and custom logic, suitable for teams that want to maintain their automation in Git.
2. Synced webhooks: A simpler approach that directly interacts with PagerDuty's API through Port, ideal for quick implementation and minimal setup.

Prerequisites

• Complete the onboarding process.

• Access to your PagerDuty organization with permissions to manage incidents.

• A PagerDuty routing key for the service you want to trigger incidents for.

  Finding your PagerDuty routing key

  To find your PagerDuty routing key (also called integration key):

  • Log in to your PagerDuty account
  • Navigate to Services in the main menu
  • Select the service you want to trigger incidents for
  • Click on the Integrations tab
  • Look for an existing "Events API V2" integration, or click Add integration and select "Events API V2"
  • The Integration Key displayed is your routing key

• 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.

Set up data model

If you haven't installed the PagerDuty integration, you'll need to create blueprints for PagerDuty incidents. However, we highly recommend you install the PagerDuty integration to have these automatically set up for you.

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 implementation

Add GitHub secrets

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

• PAGERDUTY_ROUTING_KEY - Your PagerDuty routing key for the service.
• PORT_CLIENT_ID - Your port client id How to get the credentials.
• PORT_CLIENT_SECRET - Your port client secret How to get the credentials.

Add GitHub workflow

Create the file .github/workflows/trigger-pagerduty-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 (Click to expand)

name: Trigger PagerDuty Incident

on:
  workflow_dispatch:
    inputs:
      summary:
        description: The summary of the incident to trigger
        required: true
        type: string
      source:
        description: The source of the incident
        required: true
        type: string
      severity:
        description: The severity of the incident
        required: true
        type: string
        default: "critical"
      event_action:
        description: The event action
        required: true
        type: string
        default: "trigger"
      routing_key:
        description: The routing key of the service
        required: true
        type: string
      port_context:
        required: true
        description: includes blueprint, run ID, and entity identifier from Port.
jobs: 
  trigger:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger PagerDuty Incident
        id: trigger
        uses: fjogeleit/http-request-action@v1
        with:
          url: 'https://events.pagerduty.com/v2/enqueue'
          method: 'POST'
          customHeaders: '{"Content-Type": "application/json"}'
          data: >-
            {
              "payload": {
                "summary": "${{ inputs.summary }}",
                "source": "${{ inputs.source }}",
                "severity": "${{ inputs.severity }}"
              },
              "routing_key": "${{ inputs.routing_key }}",
              "event_action": "${{ inputs.event_action }}"
            }
      
      - name: Log Response
        run: |
          echo "Response status: ${{ steps.trigger.outputs.status }}"
          echo "Response data: ${{ steps.trigger.outputs.response }}"

Set up self-service action

We will create a self-service action to handle triggering PagerDuty incidents. To create a self-service action follow these steps:

1. Head to the self-service page.

2. Click on the + New Action button.

3. Click on the {...} Edit JSON button.

4. Copy and paste the following JSON configuration into the editor.

   Trigger PagerDuty Incident (Click to expand)

   Modification Required

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

   {
     "identifier": "trigger_pagerduty_incident",
     "title": "Trigger Incident",
     "icon": "pagerduty",
     "description": "Trigger a new PagerDuty incident",
     "trigger": {
       "type": "self-service",
       "operation": "DAY-2",
       "userInputs": {
         "properties": {
           "summary": {
             "icon": "DefaultProperty",
             "title": "Summary",
             "type": "string"
           },
           "source": {
             "icon": "DefaultProperty",
             "title": "Source",
             "type": "string",
             "default": "Port"
           },
           "severity": {
             "icon": "DefaultProperty",
             "title": "Severity",
             "type": "string",
             "default": "critical",
             "enum": [
               "critical",
               "error",
               "warning",
               "info"
             ],
             "enumColors": {
               "critical": "red",
               "error": "red",
               "warning": "yellow",
               "info": "blue"
             }
           },
           "event_action": {
             "icon": "DefaultProperty",
             "title": "Event Action",
             "type": "string",
             "default": "trigger",
             "enum": [
               "trigger",
               "acknowledge",
               "resolve"
             ]
           },
           "routing_key": {
             "icon": "DefaultProperty",
             "title": "Routing Key",
             "type": "string",
             "description": "The routing key of the service"
           }
         },
         "required": [
           "summary",
           "source",
           "severity",
           "event_action",
           "routing_key"
         ],
         "order": [
           "summary",
           "source",
           "severity",
           "event_action",
           "routing_key"
         ]
       },
       "blueprintIdentifier": "pagerdutyIncident"
     },
     "invocationMethod": {
       "type": "GITHUB",
       "org": "<GITHUB_ORG>",
       "repo": "<GITHUB_REPO>",
       "workflow": "trigger-pagerduty-incident.yaml",
       "workflowInputs": {
         "summary": "{{.inputs.\"summary\"}}",
         "source": "{{.inputs.\"source\"}}",
         "severity": "{{.inputs.\"severity\"}}",
         "event_action": "{{.inputs.\"event_action\"}}",
         "routing_key": "{{.inputs.\"routing_key\"}}",
         "port_context": {
           "blueprint": "{{.action.blueprint}}",
           "entity": "{{.entity.identifier}}",
           "run_id": "{{.run.id}}",
           "relations": "{{.entity.relations}}"
         }
       },
       "reportWorkflowStatus": true
     },
     "requiredApproval": false
   }

5. Click Save.

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

Synced webhook implementation

Add Port secrets

1. In your portal, click on the ... button next to the profile icon in the top right corner.

2. Click on Credentials.

3. Click on the Secrets tab.

4. Click on + Secret and add the following secrets:

   • PAGERDUTY_ROUTING_KEY: Your PagerDuty routing key for the service.

Set up self-service action

We will create a self-service action to handle triggering PagerDuty incidents using webhooks. To create a self-service action follow these steps:

1. Head to the self-service page.

2. Click on the + New Action button.

3. Click on the {...} Edit JSON button.

4. Copy and paste the following JSON configuration into the editor.

   Trigger PagerDuty Incident (Webhook) (Click to expand)

   {
     "identifier": "trigger_incident_webhook",
     "title": "Trigger Incident (Webhook)",
     "icon": "pagerduty",
     "description": "Trigger a new PagerDuty incident",
     "trigger": {
       "type": "self-service",
       "operation": "DAY-2",
       "userInputs": {
         "properties": {
           "summary": {
             "icon": "DefaultProperty",
             "title": "Summary",
             "type": "string"
           },
           "source": {
             "icon": "DefaultProperty",
             "title": "Source",
             "type": "string",
             "default": "Port"
           },
           "severity": {
             "icon": "DefaultProperty",
             "title": "Severity",
             "type": "string",
             "default": "critical",
             "enum": [
               "critical",
               "error",
               "warning",
               "info"
             ],
             "enumColors": {
               "critical": "red",
               "error": "red",
               "warning": "yellow",
               "info": "blue"
             }
           },
           "event_action": {
             "icon": "DefaultProperty",
             "title": "Event Action",
             "type": "string",
             "default": "trigger",
             "enum": [
               "trigger",
               "acknowledge",
               "resolve"
             ]
           }
         },
         "required": [
           "summary",
           "source",
           "severity",
           "event_action"
         ],
         "order": [
           "summary",
           "source",
           "severity",
           "event_action"
         ]
       },
       "blueprintIdentifier": "pagerdutyIncident"
     },
     "invocationMethod": {
       "type": "WEBHOOK",
       "url": "https://events.pagerduty.com/v2/enqueue",
       "agent": false,
       "synchronized": true,
       "method": "POST",
       "headers": {
         "Content-Type": "application/json"
       },
       "body": {
         "payload": {
           "summary": "{{.inputs.summary}}",
           "source": "{{.inputs.source}}",
           "severity": "{{.inputs.severity}}"
         },
         "routing_key": "{{.secrets.PAGERDUTY_ROUTING_KEY}}",
         "event_action": "{{.inputs.event_action}}"
       }
     },
     "requiredApproval": false
   }

5. Click Save.

Now you should see the Trigger Incident (Webhook) action in the self-service page. 🎉

Create an automation to upsert entity in port

After each execution of the action, we would like to update the relevant entity in Port with the latest status.

To achieve this, we can create an automation that will be triggered when the action completes successfully.

To create the automation:

1. Head to the automation page.

2. Click on the + Automation button.

3. Copy and paste the following JSON configuration into the editor.

   Update PagerDuty incident in Port automation (Click to expand)

   {
     "identifier": "pagerdutyIncident_sync_after_trigger",
     "title": "Sync PagerDuty Incident After Trigger",
     "description": "Update PagerDuty incident data in Port after triggering",
     "trigger": {
       "type": "automation",
       "event": {
         "type": "RUN_UPDATED",
         "actionIdentifier": "trigger_incident_webhook"
       },
       "condition": {
         "type": "JQ",
         "expressions": [
           ".diff.after.status == \"SUCCESS\""
         ],
         "combinator": "and"
       }
     },
     "invocationMethod": {
       "type": "UPSERT_ENTITY",
       "blueprintIdentifier": "pagerdutyIncident",
       "mapping": {
         "identifier": "{{.event.diff.after.response.dedup_key}}",
         "title": "{{.event.diff.after.properties.summary}}",
         "properties": {
           "status": "triggered",
           "urgency": "high",
           "created_at": "{{.event.diff.after.createdAt}}"
         }
       }
     },
     "publish": true
   }

4. Click Save.

Now when you execute the webhook action, the incident data in Port will be automatically updated with the latest information from PagerDuty.

Let's test it!

1. Head to the Self Service hub

2. Choose either the GitHub workflow or webhook implementation:

   • For GitHub workflow: Click on Trigger Incident
   • For webhook: Click on Trigger Incident (Webhook)

3. Choose the pagerduty incident you want to trigger (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. Enter the required information:

   • For GitHub workflow: Enter the summary, source, severity, event action, and routing key
   • For webhook: Enter the summary, source, severity, and event action

5. Click on Execute

6. Done! wait for the incident's status to be changed in PagerDuty

Congrats 🎉 You've triggered 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
• Escalate an incident
• Resolve an incident