Backstage Plugins for OpenChoreo
OpenChoreo ships its own Backstage portal preconfigured for the platform. If you already run a Backstage instance and just want to add OpenChoreo capabilities, this guide is for you.
This is an alternative to forking the openchoreo/backstage-plugins repository. You install a small set of npm packages into your own Backstage workspace and wire them up.
What you get
Core (required) — delivered by a single install path:
| Capability | Details |
|---|---|
| Catalog sync | OpenChoreo namespaces become Domain entities, projects become System entities, components become Component entities, with relations preserved. |
| OpenChoreo sign-in | OIDC sign-in against the OpenChoreo IDP. The signed-in user's token flows into entity-page tab calls. Falls through to guest sign-in when your OpenChoreo cluster runs with auth off. |
| Domain entity views | Overview, Definition. |
| System entity views | Overview, Definition, Cell (architectural diagram), Diagram (catalog graph). |
| Component entity views | Overview, Definition, Deploy (per-environment runtime state). |
| Permission policy | Composable Backstage permission policy that delegates openchoreo.* permissions to the OpenChoreo authorization service and falls back to ALLOW for everything else. |
| Scaffolder actions | OpenChoreo-aware actions for use in your own scaffolder templates. |
Optional tab packs — install only the ones you want:
| Pack | Adds |
|---|---|
@openchoreo/backstage-plugin-openchoreo-observability | System tabs: Logs, Traces, Incidents, RCA Reports, Cost Analysis. Component tabs: Logs, Metrics, Alerts. |
@openchoreo/backstage-plugin-openchoreo-ci | Component tab: Build (workflow runs + trigger form). |
@openchoreo/backstage-plugin-openchoreo-workflows | Standalone org-level Workflows page. |
See the compatibility matrix for the full list of packages.
What is not in scope yet
The following live in openchoreo/backstage-plugins but are not packaged for external installation:
- External CI integrations (Jenkins, GitHub Actions, GitLab CI) — third-party plugin wiring that the in-tree portal ships preconfigured.
- Scaffolder templates — the scaffolder backend module (which ships actions) is part of Core; templates that consume those actions are still in the upstream repo.
If you need any of these today, fork the upstream repo or file an issue at openchoreo/backstage-plugins.
Compatibility
OpenChoreo plugins target a specific Backstage release line. See the compatibility matrix for the tested combinations. Installing into a Backstage app on a different release line may surface dependency-resolution issues; the troubleshooting guide lists the common ones and how to pin around them.
Where to start
- Installing into an existing Backstage app — the canonical step-by-step. Core first; opt-in tab packs follow.
- Catalog sync — what gets synced and how to tune it.
- Entity views — the full tab matrix and per-tab package mapping.
- Permission policy — composing OpenChoreo authorization with your existing policy.
- Troubleshooting — failure-mode index keyed by exact error message.