Incident & On-Call Workflows
When a service breaks at 3 a.m., the responder does not want to hunt through three tools to answer two questions: who owns this, and what do I do about it. A developer portal that already knows every service, its owning team, and its documentation is the natural place to answer both — if you surface on-call and incident context directly on the entity page. This section covers wiring on-call schedules, incident status, and runbooks into the catalog so the portal becomes the first stop in a response, not an afterthought. It sits within Developer Experience & Self-Service Platforms, because reducing time-to-context during an incident is squarely a developer-experience problem.
Why the Portal Belongs in the Response Path
During an incident, minutes spent finding context are minutes the outage continues. The classic failure is a fragmented toolchain: paging lives in one product, incident timelines in another, runbooks in a wiki nobody bookmarked. A responder alt-tabs, copies service names between search boxes, and pieces together what the portal already knows in one graph. Because the catalog is the single place that maps a service to its team, its docs, and its dependencies, it is the cheapest place to also show who is on call and whether an incident is open — no new source of truth, just a new view over the one you have.
The Two Integration Directions
On-call and incident data flow in to the portal from your paging tool — the portal reads PagerDuty (or Opsgenie) and renders the current on-call and any active incidents on the entity page. Runbooks flow the other way: they are authored as content and linked out from the entity via annotations, so the runbook is one click from the service it rescues. Keeping these directions straight is what stops the integration from becoming a tangle — one is a read of live state, the other is a durable link.
Owner Accuracy Is the Foundation
Every one of these integrations resolves through the entity’s owner. If a service’s spec.owner points at a team that no longer exists or never took over, the portal will proudly show the wrong on-call and page nobody. Incident tooling amplifies whatever the catalog believes, so the value of these workflows rests on the ownership discipline established in Service Onboarding Automation — get ownership right and the rest is wiring; get it wrong and you have built a faster way to reach the wrong person.
Frequently Asked Questions
Does this replace our paging tool?
No. PagerDuty or Opsgenie remains the system of record for schedules, escalation, and alerting; the portal is a read-only window that shows the current state next to the service. You still acknowledge and escalate in the paging tool — the portal just saves the responder from hunting for which service maps to which schedule.
What if we do not use PagerDuty?
The pattern is tool-agnostic. Any paging provider with an API for “who is on call for this schedule” and “list open incidents” can be surfaced the same way; only the client differs. The two how-tos below use PagerDuty concretely, but the entity-annotation approach and the read-live-state model carry over to Opsgenie or a homegrown system.