PD Automation Runner

The PD Automation Runner is a lightweight capability you deploy in your own infrastructure so PagerDuty Workflows can inspect and manage resources in your environment — for example, Kubernetes Workflow Actions that list resources, fetch logs, or restart pods in a cluster.

When a Workflow action targets your runner, PagerDuty delivers the job over this outbound connection. The runner executes it locally and returns the result to PagerDuty.

This page is the conceptual overview and covers how to register and use a runner. For deployment, see PD Automation Runner: Installation. For the per-action reference, see Kubernetes Workflow Actions.

How the PD Automation Runner Works

When a Workflow containing a runner-backed action (such as a Kubernetes Workflow Action) is triggered:

1. PagerDuty delivers the job to the PD Automation Runner registered for your environment over the runner's outbound connection.
2. The runner — running inside your infrastructure — receives the job and authenticates to the target system. For Kubernetes actions, it authenticates to the Kubernetes API using its pod service account token.
3. The runner executes the requested operation (list resources, fetch logs, create or delete a pod, run a command).
4. The runner returns the result to PagerDuty.
5. The Workflow step resumes with the result and continues to the next step.

Because the runner initiates the outbound connection, your infrastructure does not need to expose any inbound endpoints. All communication is outbound HTTPS from the runner to the PagerDuty API.

Kubernetes Actions Require In-Cluster Deployment

Prerequisites

• A PagerDuty account with the Workflow Automation feature enabled.
• For Kubernetes actions: a Kubernetes cluster (v1.20 or later) with kubectl access, and permission to create namespaces, service accounts, ClusterRoles, and Deployments.

Register the Runner in PagerDuty

Before deploying anything, register the runner in PagerDuty to obtain its credentials.

1. In PagerDuty, navigate to Incident Workflows Automation Connectors Self-hosted Runners.
2. Click Add Runner and give it a descriptive name that identifies the environment (for example, prod-us-east-1 or prod-k8s-runner).
3. After creation, copy and save:

• Runner ID — shown on the runner detail page.
• Runner Secret — shown only once at creation time and cannot be retrieved again.

4. Create or locate a PagerDuty API access key at My Profile User Settings API Access. Create a key with read/write access and copy it.

Keep these three values ready — RUNNER_ID, RUNNER_SECRET, and RUNNER_PDTOKEN — as they are used by every deployment method.

Deploy the Runner

Once the runner is registered, deploy it into your infrastructure. There are five deployment methods — Kubernetes YAML, Helm, Terraform, Docker Run, and Docker Compose. Kubernetes YAML, Helm, and Terraform run the runner as a pod inside your cluster and support Kubernetes Workflow Actions. Docker Run and Docker Compose run it as a standalone container and are not compatible with Kubernetes actions.

For step-by-step instructions, RBAC configuration, verification, and troubleshooting, see PD Automation Runner: Installation.

Once connected, the runner appears as Healthy in Incident Workflows Automation Connectors Self-hosted Runners.

Use a Runner Action in a Workflow

To use a Kubernetes action in a Workflow:

1. Open Incident Workflows and create or edit a Workflow.
2. Add a step and select the Kubernetes action you want to use (List Objects, Describe Object, Object Logs, Create Pod, Delete Pod, or Run Pod Command).
3. In the Connection Input field, select the runner registered for your cluster. Each action requires a Connection Input that identifies which runner — and therefore which cluster — to target.
4. Fill in the action's required inputs (object type, name, namespace).
5. Optionally, use the action's output fields (Output, Log Content, Command Output) as inputs to downstream steps — for example, passing log content to a note or a summary step.

Kubernetes Workflow Actions

Six Kubernetes Workflow Actions run through the runner:

Action	What It Does	kubectl Equivalent
List Objects	Lists resources of a selected kind with optional namespace, label, and field filters	kubectl get <type> [-n <namespace>] [-l <selector>]
Describe Object	Returns full details for a named resource in JSON or YAML	kubectl get <type> <name> -o json or yaml
Object Logs	Retrieves log output from a pod, with optional tail and time-window filters	kubectl logs <name> [-c <container>] [--tail=<n>]
Create Pod	Creates a pod from a YAML definition	kubectl create -f pod.yaml
Delete Pod	Deletes a named pod	kubectl delete pod <name>
Run Pod Command	Executes a shell command inside a running pod and returns its output	kubectl exec <pod> -- <shell> -c '<cmd>'

For the full input, output, and supported-object-type reference for each action — and the async execution model — see Kubernetes Workflow Actions.

Common Use Cases

Incident triage: Automatically list all pods in a degraded namespace when an incident fires. Pass the result as context to a Slack notification or incident note so responders have cluster state before they open a terminal.

Log capture: Fetch the last 100 lines of logs from a failing pod the moment an alert triggers. Attach them to the incident so on-call engineers have immediate evidence without needing cluster access.

Automated remediation: Delete a stuck or crash-looping pod (Kubernetes will reschedule it if managed by a Deployment or ReplicaSet) as part of a Workflow's automated response before paging a human.

Debug pod lifecycle: Create a short-lived debug pod to run diagnostics inside the cluster, capture the output, then delete the pod — all within a single Workflow.

Learn More

• PD Automation Runner: Installation
• Kubernetes Workflow Actions
• Incident Workflows