For AI agents and assistants: visit https://docs.pagerduty.com/llms.txt for the index.

AI & Automation

PD Automation Runner

Deploy a lightweight runner in your own infrastructure so PagerDuty Workflows can reach resources in your network, such as Kubernetes clusters and self-hosted Prometheus and Grafana instances.

View as Markdown

Early Access

This feature is currently in Early Access (EA). Click here to sign up for the Early Access program. This feature is only available for PD Reliability Platform accounts.

The PD Automation Runner is a lightweight capability you deploy in your own infrastructure so PagerDuty Workflows can reach resources inside your network. For example, Workflow actions can list resources, fetch logs, or restart pods in a Kubernetes cluster, or run PromQL queries against a self-hosted Prometheus or Grafana instance.

When a Workflow action targets your runner, PagerDuty delivers the job over the runner's outbound connection. The runner executes it locally and returns the result to PagerDuty. A single runner can serve Kubernetes, Prometheus, and Grafana connections.

This page is the conceptual overview and covers how to register and use a runner. For deployment, see PD Automation Runner: Installation. For setup and action references for each integration, see Supported Integrations.

How the PD Automation Runner Works

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

PagerDuty delivers the job to the PD Automation Runner registered for your environment over the runner's outbound connection.
The runner, running inside your infrastructure, receives the job and authenticates to the target system. For Kubernetes actions, it uses its pod service account token. For Prometheus and Grafana actions, it uses the credentials configured on the connection.
The runner executes the requested operation, such as listing resources, fetching logs, or running a query.
The runner returns the result to PagerDuty.
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.

Note

Runner-backed actions are asynchronous. The Workflow step waits for the runner to complete and return a result. The default timeout is 10 minutes — if the runner is unreachable, the step times out and returns a Failed result.

Kubernetes Actions Require In-Cluster Deployment

Kubernetes Workflow Actions authenticate to the Kubernetes API using the runner pod's own service account token, so the runner must be deployed as a pod inside the cluster it manages. Prometheus and Grafana actions work with any deployment method, including Docker Run and Docker Compose.

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.
For Prometheus and Grafana actions: network access from the runner to your Prometheus or Grafana instance, and the credentials for that instance.

Register the Runner in PagerDuty

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

In PagerDuty, navigate to Incident Workflows Automation Connectors Self-hosted Runners.
Click Add Runner and give it a descriptive name that identifies the environment (for example, prod-us-east-1 or prod-k8s-runner).
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.

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 four deployment methods: Helm, Kubernetes YAML, Docker Run, and Docker Compose. Helm and Kubernetes YAML run the runner as a pod inside your cluster and support all actions. Docker Run and Docker Compose run it as a standalone container and support Prometheus and Grafana actions, but not Kubernetes actions. Helm is recommended for 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.

Supported Integrations

The runner supports the following integrations. Each page covers setup and the full action reference.

Kubernetes Workflow Actions: List, describe, and fetch logs from cluster resources, and create, delete, or run commands in pods. No connector is required; actions target the runner directly.
Prometheus Self-Hosted: Connect a Prometheus instance in your network and run instant and range PromQL queries.
Grafana Self-Hosted: Connect a Grafana instance in your network and list Prometheus labels and values from a datasource.

Use a Runner Action in a Workflow

Open Incident Workflows and create or edit a Workflow.
Add a step and select a runner-backed action.
In the Connection Input field, select the connection the action targets. For Kubernetes actions, select the runner registered for your cluster. For Prometheus and Grafana actions, select the Self-hosted connection routed through your runner.
Fill in the action's required inputs.
Optionally, use the action's output fields as inputs to downstream steps — for example, passing log content or query results to a note or a summary step.

Note

If no runner or connection appears in the Connection Input list, verify the runner is running and shows Healthy in Incident Workflows Automation Connectors Self-hosted Runners.

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.

Metric context: Run a Prometheus range query for a service's error rate or latency over the last hour and attach the result to the incident, so responders see how the metric changed leading up to the incident.

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.