Acknowledge Incident In PagerDuty

Overview

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

You can implement this action in two ways:

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.
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.
Port's GitHub app needs to be installed (required for GitHub Actions implementation).
PagerDuty API token with permissions to update incidents.

Set up data model

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

Create the PagerDuty incident blueprint

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

To implement this self-service action using GitHub Actions, follow these steps to set up the required configuration:

Add GitHub secrets

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.

Add GitHub workflow

Create the file .github/workflows/acknowledge-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)

acknowledge-incident.yaml
name: Acknowledge Incident In PagerDuty
on:
  workflow_dispatch:
    inputs:
      from:
        description: The email address of a valid user associated with the account making the request.
        required: true
        type: string
      port_context:
        required: true
        description: includes blueprint, run ID, and entity identifier from Port.

jobs:
  acknowledge_incident:
    runs-on: ubuntu-latest
    steps:
      - name: Log Executing Request to Acknowledge 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(inputs.port_context).run_id}}
          logMessage: "About to make a request to pagerduty..."

      - name: Request to Acknowledge Incident
        id: acknowledge_incident
        uses: fjogeleit/http-request-action@v1
        with:
          url: 'https://api.pagerduty.com/incidents'
          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: >-
              {
                "incidents": [
                  {
                    "id": "${{ fromJson(inputs.port_context).entity }}",
                    "type": "incident_reference",
                    "status": "acknowledged"
                  }
                ]
              }

      - name: Log Acknowledge Incident 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(inputs.port_context).run_id}}
          logMessage: "Request to acknowledge incident failed ..."

      - name: Log Before Upserting Entity
        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(inputs.port_context).run_id}}
          logMessage: "Reporting the updated incident back to port ..."

      - name: UPSERT Entity
        uses: port-labs/port-github-action@v1
        with:
          identifier: "${{ fromJson(steps.acknowledge_incident.outputs.response).incidents[0].id }}"
          title: "${{ fromJson(steps.acknowledge_incident.outputs.response).incidents[0].title }}"
          blueprint: ${{fromJson(inputs.port_context).blueprint}}
          properties: |-
            {
              "status": "${{ fromJson(steps.acknowledge_incident.outputs.response).incidents[0].status }}",
              "url": "${{ fromJson(steps.acknowledge_incident.outputs.response).incidents[0].self }}",
              "urgency": "${{ fromJson(steps.acknowledge_incident.outputs.response).incidents[0].urgency }}",
              "responder": "${{ fromJson(steps.acknowledge_incident.outputs.response).incidents[0].assignments[0].assignee.summary}}",
              "escalation_policy": "${{ fromJson(steps.acknowledge_incident.outputs.response).incidents[0].escalation_policy.summary }}",
              "created_at": "${{ fromJson(steps.acknowledge_incident.outputs.response).incidents[0].created_at }}",
              "updated_at": "${{ fromJson(steps.acknowledge_incident.outputs.response).incidents[0].updated_at }}"
            }
          relations: "${{ toJson(fromJson(inputs.port_context).relations) }}"
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.getport.io
          operation: UPSERT
          runId: ${{fromJson(inputs.port_context).run_id}}

      - name: Log Upsert Entity 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(inputs.port_context).run_id}}
          logMessage: "Failed to upsert pagerduty incident to port ..."

      - name: Log After Upserting Entity
        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(inputs.port_context).run_id}}
          logMessage: "Entity upserting was successful ✅"

Set up self-service action

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

Head to the self-service page.
Click on the + New Action button.
Click on the {...} Edit JSON button.

Copy and paste the following JSON configuration into the editor.

Acknowledge 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_acknowledge_incident",
  "title": "Acknowledge Incident",
  "icon": "pagerduty",
  "description": "Acknowledge incident in PagerDuty",
  "trigger": {
    "type": "self-service",
    "operation": "DAY-2",
    "userInputs": {
      "properties": {
        "from": {
          "icon": "User",
          "title": "From",
          "description": "User Email",
          "type": "string",
          "format": "user"
        }
      },
      "required": [
        "from"
      ],
      "order": [
        "from"
      ]
    },
    "blueprintIdentifier": "pagerdutyIncident"
  },
  "invocationMethod": {
    "type": "GITHUB",
    "org": "<GITHUB_ORG>",
    "repo": "<GITHUB_REPO>",
    "workflow": "acknowledge-incident.yaml",
    "workflowInputs": {
      "from": "{{.inputs.\"from\"}}",
      "port_context": {
        "blueprint": "{{.action.blueprint}}",
        "entity": "{{.entity.identifier}}",
        "run_id": "{{.run.id}}",
        "relations": "{{.entity.Relations}}"
      }
    },
    "reportWorkflowStatus": true
  },
  "requiredApproval": false
}

Click Save.

Now you should see the Acknowledge Incident action in the self-service page. 🎉

Synced webhook implementation

You can acknowledge PagerDuty incidents by leveraging Port's synced webhooks and secrets to directly interact with the PagerDuty's API. This method simplifies the setup by handling everything within Port.

Add Port secrets

Add the following secrets to your Port account:

In your portal, click on the ... button next to the profile icon in the top right corner.
Click on Credentials.
Click on the Secrets tab.
Click on + Secret and add the following secret:
- PAGERDUTY_API_KEY - Your PagerDuty API token

Set up self-service action

Follow these steps to create the self-service action:

Head to the self-service page.
Click on the + New Action button.
Click on the {...} Edit JSON button.

Copy and paste the following JSON configuration into the editor.

Acknowledge Incident In PagerDuty (Webhook) (Click to expand)

{
  "identifier": "pagerdutyIncident_acknowledge_incident_webhook",
  "title": "Acknowledge Incident (Webhook)",
  "icon": "pagerduty",
  "description": "Acknowledge incident in PagerDuty using webhook",
  "trigger": {
    "type": "self-service",
    "operation": "DAY-2",
    "userInputs": {
      "properties": {
        "from": {
          "icon": "User",
          "title": "From",
          "description": "User Email",
          "type": "string",
          "format": "user"
        }
      },
      "required": [
        "from"
      ],
      "order": [
        "from"
      ]
    },
    "blueprintIdentifier": "pagerdutyIncident"
  },
  "invocationMethod": {
    "type": "WEBHOOK",
    "url": "https://api.pagerduty.com/incidents",
    "agent": false,
    "synchronized": true,
    "method": "PUT",
    "headers": {
      "Content-Type": "application/json",
      "Accept": "application/vnd.pagerduty+json;version=2",
      "Authorization": "Token token={{.secrets.PAGERDUTY_API_KEY}}",
      "From": "{{.inputs.from}}"
    },
    "body": {
      "incidents": [
        {
          "id": "{{.entity.identifier}}",
          "type": "incident_reference",
          "status": "acknowledged"
        }
      ]
    }
  },
  "requiredApproval": false
}

Click Save.

Now you should see the Acknowledge 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:

Head to the automation page.
Click on the + Automation button.

Copy and paste the following JSON configuration into the editor.

Update PagerDuty incident in Port automation (Click to expand)

    {
      "identifier": "pagerdutyIncident_sync_status",
      "title": "Sync PagerDuty Incident Status",
      "description": "Update PagerDuty incident data in Port after acknowledgment",
      "trigger": {
        "type": "automation",
        "event": {
          "type": "RUN_UPDATED",
          "actionIdentifier": "pagerdutyIncident_acknowledge_incident_webhook"
        },
        "condition": {
          "type": "JQ",
          "expressions": [
            ".diff.after.status == \"SUCCESS\""
          ],
          "combinator": "and"
        }
      },
      "invocationMethod": {
        "type": "UPSERT_ENTITY",
        "blueprintIdentifier": "pagerdutyIncident",
        "mapping": {
          "identifier": "{{.event.diff.after.entity.identifier}}",
          "title": "{{ .event.diff.after.entity.title }}",
          "properties": {
            "status": "{{.event.diff.after.response.incidents.0.status}}",
            "url": "{{.event.diff.after.response.incidents.0.self}}",
            "urgency": "{{.event.diff.after.response.incidents.0.urgency}}",
            "responder": "{{.event.diff.after.response.incidents.0.assignments.0.assignee.summary}}",
            "escalation_policy": "{{.event.diff.after.response.incidents.0.escalation_policy.summary}}",
            "created_at": "{{.event.diff.after.response.incidents.0.created_at}}",
            "updated_at": "{{.event.diff.after.response.incidents.0.updated_at}}"
          },
          "relations": {
            "{{.event.diff.after.entity.relations.key}}": "{{.event.diff.after.entity.relations.value}}"
          }
        }
      },
      "publish": true
   }

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!

Head to the self-service page of your portal
Click on the Acknowledge Incident (Webhook) action
Choose the PagerDuty incident you want to acknowledge (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)
Enter the email address of a valid user associated with the account making the request
Click on Execute
Wait for the incident's status to be changed in PagerDuty
Verify that the entity in Port has been updated with the new status

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

Overview​

Prerequisites​

Set up data model​

Create the PagerDuty incident blueprint​

GitHub workflow implementation​

Add GitHub secrets​

Add GitHub workflow​

Set up self-service action​

Synced webhook implementation​

Add Port secrets​

Set up self-service action​

Create an automation to upsert entity in port​

Let's test it!​

More Self Service PagerDuty Actions Examples​

Overview

Prerequisites

Set up data model

Create the PagerDuty incident blueprint

GitHub workflow implementation

Add GitHub secrets

Add GitHub workflow

Set up self-service action

Synced webhook implementation

Add Port secrets

Set up self-service action

Create an automation to upsert entity in port

Let's test it!

More Self Service PagerDuty Actions Examples