Backstage PagerDuty plugin setup for on-call

How the Backstage PagerDuty plugin puts on-call and incidents on service pages

Engineers working in a service page often switch to PagerDuty to learn who is on call and whether anything is firing against the service. PagerDuty's own Backstage plugin is the supported way to bring that information into the portal, and it reads on-call and incident data per service so each entity page can show the people and alerts tied to that service. The plugin is a read view. PagerDuty remains the system of record for schedules, escalation policies, incidents and acknowledgements, and any change an engineer makes still happens in PagerDuty itself.

Before you plan the rollout, confirm the current package name, the configuration keys and the token type in PagerDuty's plugin documentation, because these details change between plugin releases and the names in older community posts may no longer apply. Ask PagerDuty or check their documentation for which API token types the plugin accepts, what each token can read, and whether the plugin needs a backend component, a frontend component or both. Also confirm how it finds the service: whether it matches a PagerDuty service to a catalog entity through an annotation on the entity or through a service identifier you write into the descriptor, since that choice decides how much manual mapping your catalog owners must maintain.

Treat the mapping as a catalog governance task, not a plugin setting. A service page only shows PagerDuty data when each component has a clear, unique link to one PagerDuty service, so duplicate or unowned entities will show the wrong on-call rota or none at all. Decide early who is accountable for keeping those links correct when services are renamed, split or retired, and check how the plugin behaves when a link is missing so that gaps are visible to owners rather than silently empty.

What you need in place before connecting PagerDuty

The PagerDuty plugin reads from a working Backstage instance, so the portal, its sign-in and its catalog need to be settled first. The cards below cover the Backstage version line, the identity and catalog base, the PagerDuty account and token, and the network path from the backend to PagerDuty's API.

Supported Backstage and Node.js lines

Confirm your Backstage release is on a line that receives fixes. The versioning policy supports exactly two adjacent even-numbered Node.js releases, and as of Backstage 1.46.0 these are Node.js 22 and 24. Check the plugin's peer dependency range against your Backstage version before installing, and plan the upgrade first if you are behind. The main release line ships monthly, while the next line ships weekly for teams that test early.

Working sign-in without guest access

PagerDuty data should only reach people who are signed in with a known identity. Confirm that your identity provider resolves to one catalog user for each person, using sign-in resolvers, and that guest access is off in production. Without this, a user's on-call view cannot be tied to the right organizational context, and access reviews become harder to explain to auditors.

Catalog with owners already defined

The plugin maps PagerDuty services to catalog entities, so each service's owning team group must already exist in the catalog. Ask whether your group entities are loaded from your identity directory or maintained in descriptor files, and confirm that each team that carries on-call duty has a group entity. Teams missing from the catalog will show incidents with no owner to route to.

PagerDuty plan and account features

Confirm with PagerDuty which plan and account features your organization holds, including whether on-call schedules and incident data are available through the API for your account. Feature availability varies by plan, so do not assume a capability from the product name. Ask PagerDuty or your account owner to confirm this in writing before you plan the mapping work.

API token with read-only scope

Create a PagerDuty API token for the plugin with the narrowest access that still returns schedules and incidents. Confirm the token type and permissions in your PagerDuty account, store it in your secrets system rather than in frontend configuration, and assign a named owner who can rotate it. A token tied to a departed employee's account will stop working and is hard to trace.

Network path to PagerDuty's API

The Backstage backend, not the browser, calls PagerDuty's API, so the backend host needs outbound HTTPS to PagerDuty. Check egress rules, proxy settings and any allow-list your security team maintains for regulated networks. Test the path from the same runtime that will host the backend, since a laptop test can pass where production egress is blocked.

How services in PagerDuty become entities in the catalog

The link between PagerDuty and Backstage is a match between a PagerDuty service and a Backstage Component entity. The entity carries an annotation that names the PagerDuty service, and the plugin uses that value to find the right service and its on-call data. The annotation key and any entity-level settings, such as which PagerDuty instance to query when you run more than one, are defined by the plugin, so confirm the exact key and format in the plugin's README before you write it into descriptors. Treat the annotation as a contract: it must match exactly one PagerDuty service, and a typo or a service that was renamed or deleted in PagerDuty will show an empty or failed panel rather than a clear error.

On each page load, the Backstage backend asks PagerDuty for the on-call schedules and incidents tied to the service named on that entity. The PagerDuty API token is configured on the backend and is used only by server-side code, so the browser never receives it. Plan the token's scope with the PagerDuty administrator before the build starts, since it determines which services and schedules the portal can read. Also confirm how the plugin handles user-level lookups, because on-call names must resolve to Backstage users to be useful, and that depends on how your identities are mapped in the catalog.

Two mapping cases need an explicit decision. When one team owns several PagerDuty services, you can either point several entities at the same service or model each deployable as its own component and give each its own annotation. The first is simpler but shows the same incidents in multiple places, while the second matches the catalog more closely but multiplies the annotations to maintain. Some PagerDuty services will have no entity at all, such as shared infrastructure or legacy queues. Those incidents will not appear in any service page, so decide who watches them and whether a catalog entity should be created for them. Review unmatched services during rollout rather than assuming coverage.

Configuration sequence for the PagerDuty plugin

This sequence connects your Backstage instance to PagerDuty so that each in-scope service entity shows its on-call schedule and open incidents, with credentials kept on the backend and each step verified before the next begins.

Create a scoped PagerDuty API token
A PagerDuty account administrator creates a token for the Backstage backend, using the narrowest access level the plugin's documentation names for reading services, schedules and incidents. Confirm the required scopes with the plugin's README before issuing the token, and record which PagerDuty account or user the token belongs to so it can be rotated later. Done means the token exists in PagerDuty and you can see its owner and creation date in the admin view, but you have not yet pasted it anywhere.
Store the token as a backend secret
The platform engineer places the token in your secret store or in an environment variable injected into the backend container, never in app-config.yaml committed to the repository. Reference it from configuration by name only. Done means a search of the repository for the token value returns nothing, and the backend pod or process reads the variable at startup when you print its presence (not its value) in logs.
Install matching plugin packages
The developer adds the PagerDuty frontend and backend plugin packages from the vendor-maintained repository, choosing the versions that match your Backstage release line. Install every @backstage package at the same release line, then run the dependency install and type check. Confirm the package versions against the plugin's compatibility notes before you commit the lockfile. Done means the install completes without peer dependency errors and the lockfile shows the expected plugin versions.
Configure the PagerDuty connection
The platform engineer adds the PagerDuty connection block to app-config.yaml, pointing the token reference at the backend secret from step two and setting the API base URL for your PagerDuty region or account type. Keep the frontend free of the token; the backend performs all PagerDuty calls. Done means the backend starts with no configuration validation errors, and the log shows the PagerDuty integration initialized without printing the token.
Add the identifier annotation to entities
Service owners add the PagerDuty service annotation to the catalog-info.yaml descriptor of each in-scope component, using the service identifier from PagerDuty. Start with one representative service so the mapping is proven before you roll it out. Done means the entity validates in the catalog and the annotation value matches the PagerDuty service ID you copied from the PagerDuty service page.
Register the entity card or tab
The frontend developer adds the PagerDuty card or tab to the service entity page in the app's entity page composition, limiting it to entities that carry the annotation so unrelated components do not show empty panels. Rebuild the frontend and open the test entity. Done means one entity page shows its PagerDuty service name and the current on-call responder, and an entity without the annotation shows no PagerDuty card.
Verify with a known service and incident
The on-call lead checks the mapped entity against the PagerDuty service it names, comparing the on-call person and any open incident with what PagerDuty itself shows. Ask the platform team to confirm that the token scope blocks write actions it does not need, by attempting a read-only view and reviewing the audit trail in PagerDuty. Done means the displayed schedule and incident state match PagerDuty for at least one service, and the sign-off is recorded before you expand the annotation to other entities.

Which PagerDuty fields map to which Backstage data

This table compares each PagerDuty object with the Backstage entity field, annotation or display element that carries it. Read it top to bottom when you configure the plugin, and confirm each field name against the plugin's current documentation before you rely on it. The main takeaway is that the ownership link between catalog groups and PagerDuty teams causes most empty views.

PagerDuty object	Where it appears in Backstage	What to check
PagerDuty service	Entity annotation that holds the PagerDuty service identifier on a component or service entity	Confirm the annotation key in the plugin documentation and copy the service ID from PagerDuty, not the display name
Escalation policy	On-call view for the mapped service, showing the policy levels and their targets	Verify that the policy is attached to the same service you annotate, since one policy can cover several services
On-call schedule	On-call section of the entity page, listing who is currently on call and upcoming shifts	Check that the schedule is linked through the escalation policy and that the API token can read it
User currently on call	Name shown in the on-call view, resolved from the PagerDuty user record	Compare PagerDuty user emails with Backstage user entities so the names resolve to the same person
Incident status	Open and acknowledged incident list on the service entity	Confirm which statuses the plugin displays and whether resolved incidents appear in history
Incident urgency	Urgency label on each incident row, typically high or low	Confirm how the plugin sorts or filters by urgency before you build a team view on it
PagerDuty team and catalog Group	Ownership shown through the Group entity referenced by the component's owner field	Match the Group name to the PagerDuty team name; mismatched names are the most common cause of empty views

How to test the integration before the whole catalog depends on it

Run a pilot on a small set of entities owned by one team before any other team relies on the PagerDuty views. Agree the test plan with the service owners, the PagerDuty administrator and the Backstage team before rollout starts, and write down the pass criteria for each check. The first check is identity: open each pilot entity's on-call panel and compare every displayed name with the current schedule in PagerDuty for the matching service. Confirm that the schedule override and the escalation policy that feed the view match what the on-call engineers see in PagerDuty itself. Repeat the comparison after a planned rotation handover, because that is where stale or mismatched names usually appear.

The second check is incident flow. Trigger a test incident on a non-production PagerDuty service mapped to a pilot entity, then confirm that it appears in the entity's incident list with the same status, urgency and title shown in PagerDuty. Resolve it and confirm the status changes in Backstage. Include one entity with no mapping in the pilot, and confirm it shows a clear empty state that says no PagerDuty service is linked, rather than an error or a blank panel. Also review the backend logs for failed calls to the PagerDuty API during these tests, since a token with insufficient scope often fails quietly on the frontend while the logs show the rejected request.

The third check confirms the token is read-only in practice, not only in intent. Using a test PagerDuty account and a token issued for the pilot, attempt one write action such as creating an incident or changing a schedule through the API. The request should be refused. If it succeeds, stop the pilot, revoke the token and review the scopes the token was granted before anyone else connects to the catalog. Record the results against the agreed criteria, and do not expand the mapping to other teams until the team owners have signed off on all three checks.

Securing the PagerDuty token and the data it exposes

On-call schedules and incident data name real people and show how your teams respond to failure, so the plugin needs the same access discipline as your other production systems. The controls below cover the token, where it lives, who can see the data in Backstage and what you can later prove about access.

Use a read-scoped token from a service user

Create a dedicated PagerDuty service user for the Backstage backend and issue the API token to that user, not to an engineer's personal account. Limit the token to read access for services, schedules and incidents, since the portal only displays this data. Confirm the exact scopes the plugin needs in PagerDuty's documentation before you grant anything, because scope names and required permissions can change between plugin versions. A personal token breaks when its owner leaves and carries that person's full permissions.

Store the token in the backend secret store

Keep the token in the backend configuration as a secret that is read from your secret manager or environment at runtime, and never in a committed app-config.yaml file. Do not expose it through any key that the frontend bundle can read, because anything in the browser can be copied by any signed-in user. Check your build output and your repository history for accidental values before go-live, and rotate the token if one was ever committed.

Rotate the token and name an owner

Assign one named team to own the PagerDuty token, record its creation date, and set a rotation schedule that your security policy requires. Rotation needs a short window in which the old and new tokens both work, or the plugin will show empty on-call panels during the change. Document where the token is stored so the owner can replace it without searching across environments.

Set sign-in resolvers and disable guest access

Who sees on-call data depends on who can sign in. Configure sign-in resolvers so each identity provider maps to the same catalog user, and turn off guest access in production so anonymous visitors cannot reach entity pages. Test with an account from outside the owning team to confirm that the pages render only for users your access model allows. Note that the plugin itself may not enforce per-team visibility, so confirm with the plugin's documentation what it filters.

Treat on-call names as personal data

On-call rotations list engineers' names, contact details and working patterns, which counts as personal data under most privacy regimes. Decide which roles should see names, such as the owning team and its managers, and whether other teams should see only a team-level contact. Record this decision in your data inventory and check it with your privacy lead before the plugin shows schedules to the wider organization.

Log who viewed which service

Ask whether Backstage's audit logging captures page views and API calls that return PagerDuty data, and whether those logs reach your central log platform with the user identity attached. If the built-in logs do not record which user opened which service's on-call panel, plan a proxy or log filter that does. Keep the retention period aligned with your incident and access review policy.

What each role needs to set up and use the plugin

Platform administrators install the PagerDuty plugin, configure the Backstage backend with the API token, and decide how the portal reaches PagerDuty. This role owns the credential lifecycle, the choice of token type, and the decision about which PagerDuty account or subdomain the portal is allowed to read. The work happens in the Backstage configuration and the secrets store that feeds it, not in the frontend.

Access they need: Write access to the Backstage app configuration and the deployment secrets, plus a PagerDuty user or integration context able to create a read-only API token for the account.
Decisions they own: Which token type to use, how often it rotates, which PagerDuty account the portal reads from, and where the token is stored.
Token scope: Ask the PagerDuty administrator to confirm which read permissions the chosen token type grants, and request no more than the portal needs to display schedules and incidents.
Secrets handling: Keep the token in the backend secret store, never in a frontend bundle or a committed config file.
What they should not be given: Write rights to PagerDuty services or schedules. The portal only needs to read them, and an administrator who can change on-call rotations from the portal widens the blast radius of a leaked token.

Before sign-off, confirm the plugin version against the Backstage release line your portal uses.

Why on-call or incident data is missing or wrong

This table lists the failures teams most often see when PagerDuty data appears on an entity page, with the likely cause and the first thing to check. Work through the rows in order, since a token or identifier problem often hides behind an empty card or a wrong name. The main takeaway is that most failures trace back to how the service is mapped to the entity or how the token is scoped, not to PagerDuty itself.

Symptom	Likely cause	Check first
Empty card on an entity	The entity has no PagerDuty service annotation, or the annotation value does not match a PagerDuty service ID or name exactly	Confirm the annotation on the entity descriptor and compare it with the service ID shown in the PagerDuty service URL
On-call person shown as the wrong user	Schedule override or a layer that rotates across time zones, so the current responder differs from what the team expects	Open the schedule in PagerDuty at the current time and check overrides and layer boundaries against the portal's time zone
Stale data on the page	Plugin or proxy caching, or a schedule change made recently that the cached response has not picked up yet	Reload after a short wait, then check the cache settings in the plugin configuration and the backend logs for the last successful fetch
401 or 403 responses from PagerDuty	The API token is invalid, expired, revoked, or lacks read access to the services, schedules or incidents the plugin requests	Verify the token in PagerDuty under the user or integration that owns it, and confirm its permissions cover the endpoints the plugin calls
Plugin loads but returns no incidents	Incidents are filtered by status or time window, the service ID points to a different service, or the token user cannot see the service	Query the same service in PagerDuty with the same token and status filter, then compare the result with what the plugin requests
Entity shows another team's service	Two entities share a service name or ID, or an annotation was copied from a neighboring component during scaffolding	Search the catalog for the service identifier and confirm each annotation matches exactly one owned entity and one PagerDuty service
Responder does not match a catalog user	Sign-in identity and the PagerDuty user email do not resolve to the same person, so the name is shown without a link or is wrong	Compare the email on the PagerDuty user with the email on the Backstage user entity and the sign-in resolver output

Questions teams ask before connecting PagerDuty to Backstage

How much effort does a PagerDuty integration in Backstage take?

The effort depends mostly on three things: the number of catalog entities you need to map, the number of PagerDuty accounts involved, and the identity model that decides who can see what. A single account with a few dozen services is a small mapping exercise. Several accounts, shared services and entities owned by different teams add review cycles and naming decisions. Cost comes from two places: internal staff time or a partner's fixed-scope fee, and ongoing upkeep. The upkeep is recurring work: updating mappings when services move, reviewing the plugin after Backstage upgrades, and rotating the API token. When you ask for a quote, ask which of these items are included and how the mapping review is handled.

Can our internal team connect PagerDuty to Backstage without a partner?

Yes, if your team already runs a Backstage instance and has engineers comfortable with its backend configuration and plugin wiring. The work is not large in code terms, but it touches the token, the backend, the catalog annotations and the sign-in model, so mistakes are easy to make in the wrong place. A partner adds most value on the decisions that are hard to reverse: how PagerDuty services map to entities, how token scope is set, and how Backstage identities line up with PagerDuty users. Ask yourself whether someone on your team will own the integration after go-live. If the answer is no, plan for that ownership before you build, whichever route you choose.

How long does a PagerDuty pilot take, and what sets the timeline?

No general duration can be given for this integration, because the timeline depends on your environment. The main variables are how many services and entities must be mapped, whether one or several PagerDuty accounts are involved, how long your change approval takes, and whether the identity decisions are already settled. A pilot covering one team's services usually moves faster than one covering the whole catalog, because the review of mappings is the slowest step. For a planning figure, ask any implementation partner for a written scope with milestones, and ask your own team to list the services and accounts in scope before the conversation starts.

What does the work need from the PagerDuty admin and service owners?

The PagerDuty admin creates the API token and decides its scope, so the token only reads the on-call and incident data the portal shows. The admin also confirms which accounts and services are in scope. Service owners confirm that each catalog entity points to the correct PagerDuty service, because a wrong mapping shows another team's incidents on the wrong page. Ask your engineers to confirm the exact entity annotation the plugin reads in its own documentation, since the mapping key is set by the plugin and should not be guessed. Agree early on who approves mapping changes, otherwise the mapping file drifts as services are renamed or split.

Does the PagerDuty plugin replace PagerDuty?

No. The plugin displays on-call schedules and incident context inside Backstage service pages, but PagerDuty remains the system of record for paging, escalation policies, notifications and incident response. Engineers still acknowledge and resolve incidents in PagerDuty or its own tools. The benefit in Backstage is context: when an engineer opens a service, they see who is on call and what is open against that service without switching tabs. Teams that expect Backstage to route pages or replace escalation logic will be disappointed, so state this boundary in your internal rollout notes.

Where should the PagerDuty API token live, and who can see it?

The token should be held by the Backstage backend, supplied through your secrets handling and never placed in frontend configuration or in files committed to source control. The backend calls PagerDuty on behalf of signed-in users, so a leaked token would expose data to anyone who could reach that secret. Use a token scoped to read the data the portal needs, and document who holds it and how it is rotated. Check the plugin's documentation for the permissions it expects, and confirm them with your PagerDuty admin before the token is issued. Review the scope again whenever the plugin version changes.

What happens to the setup when Backstage or the plugin is upgraded?

Backstage upgrades move all @backstage packages together, using the Backstage CLI version bump command, and the Backstage Upgrade Helper shows template changes between versions. Third-party plugins such as the PagerDuty plugin ship on their own schedule, so each upgrade needs a check that the plugin version is compatible with your Backstage version. Your mapping file, token configuration and any custom code should live in version control so that an upgrade becomes a reviewed change rather than a rebuild. Plan a test run against a non-production instance before each upgrade, and budget for that test as recurring work in your operating model.

How DeployOpen scopes and delivers the PagerDuty integration

DeployOpen approaches the PagerDuty plugin for Backstage as a scoped piece of work inside your own Backstage instance, starting from which teams, services and on-call schedules need to appear on entity pages. We agree the mapping, token permissions and verification steps in writing before any configuration begins.

How we scope

Inventory which Backstage components map to which PagerDuty services, and who owns each mapping
Agree the API token type, its permissions and who holds it before any configuration starts
Confirm which Backstage backend and frontend locations your instance runs, and where secrets will be stored

How we build

Install and configure PagerDuty's own plugin in your Backstage repository, pinned to your release line
Add the entity annotations that link each catalog component to its PagerDuty service
Test that on-call and incident views load for representative components, with the token kept on the backend

How we hand over

Deliver the written configuration, annotation conventions and token rotation steps for your team
Document the service mapping so new components follow the same pattern when they are registered
Walk your platform and on-call owners through how incidents and schedules appear on entity pages

How we support

Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts
Ongoing support, plugin upgrades and continuous testing are available as a retainer
Quotes follow from the written scope, so ask for the mapping and token details to be itemized

Backstage PagerDuty plugin for on-call and incidents