Skip to main content

Create PagerDuty Incident Action

Overview​

This self service guide provides a comprehensive walkthrough on how to create an 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:

  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/create-an-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
create-an-incident.yaml
on:
  workflow_dispatch:
    inputs:
      port_payload:
        required: true
        description: "Port's payload, including details for who triggered the action and general context (blueprint, run id, etc...)"
        type: string
    secrets: 
      PAGER_TOKEN: 
        required: true
      PORT_CLIENT_ID:
        required: true
      PORT_CLIENT_SECRET:
        required: true
jobs: 
  trigger:
    runs-on: ubuntu-latest
    steps:
      - uses: port-labs/pagerduty-incident-gha@v1
        with:
          portClientId: ${{ secrets.PORT_CLIENT_ID }}
          portClientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          token: ${{ secrets.PAGER_TOKEN }}
          portRunId: ${{ fromJson(inputs.port_payload).context.runId }}
          incidentTitle: ${{ fromJson(inputs.port_payload).payload.properties.title }}
          extraDetails: ${{ fromJson(inputs.port_payload).payload.properties.extra_details }}
          urgency: ${{ fromJson(inputs.port_payload).payload.properties.urgency }}
          service: ${{ fromJson(inputs.port_payload).context.entity }}
          blueprintIdentifier: 'pagerdutyIncident'

Port Configuration​

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

Create 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": "pagerdutyIncident_create_incident",
  "title": "Create Incident",
  "icon": "pagerduty",
  "description": "Notify users and teams about incidents in the service",
  "trigger": {
    "type": "self-service",
    "operation": "CREATE",
    "userInputs": {
      "properties": {
        "title": {
          "icon": "DefaultProperty",
          "title": "Title",
          "type": "string"
        },
        "extra_details": {
          "title": "Extra Details",
          "type": "string"
        },
        "urgency": {
          "icon": "DefaultProperty",
          "title": "Urgency",
          "type": "string",
          "default": "high",
          "enum": [
            "high",
            "low"
          ],
          "enumColors": {
            "high": "yellow",
            "low": "green"
          }
        },
        "from": {
          "title": "From",
          "icon": "User",
          "type": "string",
          "format": "user",
          "default": {
            "jqQuery": ".user.email"
          }
        }
      },
      "required": [
        "title",
        "urgency",
        "from"
      ],
      "order": [
        "title",
        "urgency",
        "from",
        "extra_details"
      ]
    },
    "blueprintIdentifier": "pagerdutyIncident"
  },
  "invocationMethod": {
    "type": "GITHUB",
    "org": "port-pagerduty-example",
    "repo": "test",
    "workflow": "create-an-incident.yaml",
    "workflowInputs": {
      "{{if (.inputs | has(\"ref\")) then \"ref\" else null end}}": "{{.inputs.\"ref\"}}",
      "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",
              "omitPayload": false,
              "omitUserInputs": true,
              "reportWorkflowStatus": true,
              "org": "port-pagerduty-example",
              "repo": "test",
              "workflow": "create-an-incident.yaml"
            },
            "trigger": "{{.trigger.operation}}"
          },
          "properties": {
            "{{if (.inputs | has(\"title\")) then \"title\" else null end}}": "{{.inputs.\"title\"}}",
            "{{if (.inputs | has(\"extra_details\")) then \"extra_details\" else null end}}": "{{.inputs.\"extra_details\"}}",
            "{{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 Create Incident action in the self-service page. 🎉

Let's test it!​

  1. Head to the Self Service hub
  2. Click on the Create Incident action
  3. Enter the required data for Incident Title, Service, and optionally include Extra Details and Urgency.
  4. Click on Execute
  5. Done! wait for the incident's status to be changed in PagerDuty

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

More Self Service PagerDuty Actions Examples​