What a Backstage implementation involves
Backstage is an open-source framework for building developer portals. It was created at Spotify, is licensed under Apache 2.0, and has been a CNCF incubating project since March 2022. Its core features are the software catalog, Software Templates for creating new projects, TechDocs for documentation stored next to code, and search, with a large set of plugins for CI, Kubernetes, cloud and monitoring tools.
Backstage ships as a framework you assemble into your own TypeScript and React application. You generate an app, choose and configure plugins, write the glue that is specific to your organization and deploy it like any other service. That makes the portal fit your platform closely, and it also means someone has to own the codebase, its dependencies and monthly upgrades.
A useful portal depends on catalog data, templates that encode golden paths, and teams who keep both current. DeployOpen designs the catalog model with your platform team, builds templates and plugins, and sets up the upgrade practice your team will run.
Design the software catalog
Catalog decisions are hard to change once hundreds of repositories carry catalog-info.yaml files.
| Decision | What to settle | Why it matters |
|---|---|---|
| Entity kinds | How Component, API, Resource, System and Domain map to your services, libraries, databases, products and business areas. | Consistent kinds make dependency views, ownership reports and scorecards meaningful. |
| Ownership | Which Group owns each entity, and where Group and User entities come from (GitHub or GitLab org data, Microsoft Entra ID, LDAP). | Every entity needs an owner that maps to a team that exists in your identity source. |
| Ingestion | Whether entities are discovered from repositories, registered by templates or produced by custom entity providers from a CMDB or cloud inventory. | Discovery scales, while custom providers fill gaps for systems without a repository. |
| Annotations and metadata | A short list of required annotations for CI, Kubernetes, on-call and documentation, plus lifecycle and tier values. | Plugins find their data through annotations, so missing ones leave empty tabs. |
Golden paths, documentation and search
The features that usually justify a portal, and the design work each needs.
Software Templates
Templates collect parameters through forms, then run actions that fetch a skeleton, publish a repository, open pull requests and register the new component. Build a small number of templates that encode your supported stacks, CI, security checks and catalog registration.
TechDocs
TechDocs renders Markdown from each repository with MkDocs. For production, build documentation in CI and publish it to object storage. Recent releases restrict MkDocs plugins to an allowlist, so check custom documentation setups during upgrades.
Search
Search indexes the catalog, TechDocs and any other source that has a collator. The default Lunr engine is in memory and discouraged for production. Use the PostgreSQL engine or Elasticsearch or OpenSearch, depending on volume and existing services.
Operational views
Kubernetes, CI, on-call and monitoring plugins show the state of a component on its catalog page. Start with a few your teams already use.
Configuration, plugins and custom code
Much of Backstage is set in app-config.yaml files layered by environment: integrations, auth providers, catalog locations, proxy routes and plugin options. Secrets come from environment variables.
Open-source plugins cover many tools, with uneven maintenance. Before adopting one, check recent releases, compatibility with the new frontend and backend systems, and who maintains it. Each plugin added is a dependency to keep current.
Organization-specific needs such as an internal deployment API, a cost view or a custom scaffolder action are built as plugins or backend modules in TypeScript. The backend system composes plugins, modules, services and extension points, which keeps custom code isolated from core packages.
Since release 1.49.0 in March 2026, new apps use the new frontend system by default, and that release was marked as the release candidate for its 1.0 version. Older apps on the legacy system can keep running and migrate in steps. Plan that migration explicitly, because plugins built for one system need adapters or updates for the other.
Integrations and migration
Typical integrations are source control (GitHub, GitLab, Bitbucket or Azure DevOps) for discovery, templates and TechDocs, your identity provider for sign-in and org data, Kubernetes clusters, CI systems, cloud accounts and on-call tooling. Plugins that call third-party APIs from the browser usually go through the Backstage proxy, so the proxy routes and the credentials behind them need the same review as any service integration.
Most organizations start from a wiki, a spreadsheet of services, a CMDB or a set of README files. Migration means generating catalog-info.yaml files from that inventory, opening pull requests so teams confirm ownership, and moving documentation into repositories for TechDocs.
Roll out with one or two platform-friendly teams first, then a wider group once templates and catalog pages work for them. Enablement covers writing catalog files, using and contributing templates, writing TechDocs and requesting plugin changes, plus deeper training for the engineers who will maintain the app.
Hosting, security and upgrades
What does a production deployment look like?
A container image built from your app, running one or more backend instances behind a load balancer, with PostgreSQL as the database (each plugin gets its own logical database) and a shared cache such as Redis, Valkey or Memcached. SQLite and the in-memory cache are meant for development and tests.
How do sign-in and access control work?
Backstage has auth providers for GitHub, GitLab, Microsoft (Azure), Google, Okta, Keycloak and others. Sign-in resolvers map each login to a User entity in the catalog, so org data must be ingested first. By default, Backstage endpoints are not protected and all actions are available to anyone who can reach them. The permissions framework adds policies that restrict catalog, scaffolder and plugin actions, and you have to write or configure those policies.
What should we harden?
Disable the guest provider in production, use scoped tokens or GitHub App credentials for integrations, restrict which templates can publish where, limit proxy routes to the hosts plugins need, and review scaffolder actions that run shell commands or touch infrastructure.
How often does Backstage release, and how do we upgrade?
The main release line ships monthly, with a weekly next line for early access. Upgrade with yarn backstage-cli versions:bump, then review the create-app changelog and the Upgrade Helper for changes to the generated app and backend packages. High and critical security fixes may be backported to releases from the last six months where feasible, so falling far behind removes that safety net.
Backstage operating ownership
A developer portal is a product with users, so it needs a team that treats it as one.
Portal team
- Owns the app repository, plugins and monthly upgrades.
- Reviews community plugins before adoption.
- Runs the deployment, database and search backend.
Platform engineering
- Maintains templates that encode supported stacks.
- Keeps CI, security checks and infrastructure in templates current.
- Retires templates for unsupported stacks.
Service teams
- Keep catalog-info.yaml accurate for their components.
- Write and update TechDocs in their repositories.
- Request new plugins or template changes.
Security
- Reviews permission policies and integration credentials.
- Approves scaffolder actions that change infrastructure.
- Tracks advisories for Backstage and its dependencies.
Backstage implementation questions
Do we need TypeScript skills in-house?
Yes, for the long term. Configuration and catalog work need little code, but upgrades, custom plugins and template actions are TypeScript and React work. Plan for at least part of an engineer's time on the portal after launch.
Should we self-host or use a commercial distribution?
Commercial Backstage distributions and hosted portals exist and reduce upgrade work in exchange for license costs and less control over the codebase. Self-hosting keeps full control and keeps data in your environment. We help you compare them against your team capacity and plugin needs.
How do we keep catalog data accurate?
Generate entities from authoritative sources where you can, validate catalog files in CI, show missing owners and annotations in a report, and make the portal the place where teams already look for service information so they have a reason to update it.
Can Backstage replace our CMDB?
It can hold the developer-facing view of services, APIs and ownership, and custom entity providers can sync with a CMDB. Asset, contract and IT service management data usually stay in the CMDB, so define which system is authoritative for each field.
Scope and handover
Effort depends on the number of repositories and teams, the state of existing service and ownership data, how many templates and custom plugins are needed, the integrations required, whether a legacy Backstage app needs migrating to the new frontend and backend systems, and your hosting standards. Catalog data and adoption work usually take longer than standing up the app.
DeployOpen designs the catalog model, builds the Backstage app, templates and custom plugins, integrates source control, identity, Kubernetes and CI, deploys and hardens it in your environment, and runs the first upgrade with your team. Handover includes the app repository with documented customizations, catalog conventions and validation, template catalog with owners, permission policies, upgrade runbook and backup and restore procedure.
