backstage

How to build UI in this repo — the bui (@backstage/ui) design system vs legacy @backstage/core-components + MUI v4, which to reach for, and how to read Backstage Storybook component/story source. Use when creating or changing pages, cards, layouts, buttons, or any frontend component.

Patterns for implementing tables. Covers the bui Table ('@backstage/ui') — preferred for new, simple tables — and the feature-rich '@backstage/core-components' Table with search, filtering, and column-visibility persistence.

Common rules for working with this repository

Read, classify, and triage Sentry issues for this Backstage app, propose mitigations, and decide their disposition (fix, resolve, mute, or escalate). Use when given a Sentry issue URL (giantswarm.sentry.io/issues/...), asked to investigate a Sentry error/exception/CSP violation, asked why an image/script/style/font was blocked on a page, or asked to mute/ignore noisy Sentry issues.

Build Backstage backend plugins with createBackendPlugin and core services: DI, httpRouter, secure-by-default auth, Knex DB, routes, testing. Use for APIs and background jobs.

Build Backstage frontend plugins with the new Frontend System: createFrontendPlugin, blueprints, routes, Utility APIs, testing. Use for pages, nav, entity content, or cards.

Create a changeset file for versioning packages. Use when the user wants to document changes for release, create a changelog entry, or bump package versions.

Update Backstage dependencies to the latest version. Use when the user wants to update backstage, upgrade backstage packages, bump backstage version, or keep backstage up to date.

Querying Prometheus/Mimir metrics and registering new metrics in the central metrics registry.

Search upstream Backstage and community-plugins repositories for implementation patterns, API usage, and reference code. Use when implementing features that may exist upstream, checking idiomatic Backstage patterns, or when explicitly asked to look at upstream code.

Component file structure and organization patterns for React components in this repository