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.
- Pre-built scaffolder templates — the scaffolder backend module (which ships actions) is part of Core, but the default templates that consume those actions are still in the upstream repo. To author your own templates that reuse the actions, see Custom Backstage Scaffolder Templates.
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.
To author your own scaffolder templates that reuse the OpenChoreo scaffolder actions, see Custom Backstage Scaffolder Templates under Platform Setup.