Backstage is an open source framework for building an internal developer portal, a single web application where engineers can find services, spin up new projects from templates, read documentation, and see who owns what. It was created at Spotify and donated to the Cloud Native Computing Foundation in 2020, and it now ships as a set of React-based frontend components paired with a Node.js backend and a plugin system. Companies don't run "Backstage" out of the box so much as they build their own portal on top of it, wiring in their own data sources, pipelines, and cloud accounts. The result, when it works, is a front door to engineering that replaces a pile of wikis, spreadsheets, and tribal knowledge. It also becomes the one place new hires and cross-team contributors go first, which changes onboarding time as much as it changes daily lookup habits.
The reason Backstage exists is that large engineering organizations lose enormous amounts of time just figuring out what exists. As companies move to microservices and cloud infrastructure, the number of services, pipelines, and repos multiplies faster than anyone's ability to track them in a spreadsheet. Engineers end up asking in chat who owns a service, where its docs live, or how to spin up something new, and the answers depend on someone remembering. Backstage was built to turn that tribal knowledge into a searchable, structured catalog that stays current because it is tied to how software actually gets built and deployed. Spotify's own internal engineers were the first users, and the pain that drove the project was concrete: with hundreds of services and squads, even senior engineers were losing hours a week to basic discovery questions that a well-maintained catalog answers in seconds.
What distinguishes Backstage from a generic wiki or admin dashboard is its catalog model and its plugin architecture. Every piece of software, infrastructure, or team is described as an entity with a YAML metadata file that lives next to the code, so ownership, dependencies, and links update automatically as part of normal development instead of through a separate documentation exercise. On top of that catalog sits a plugin system: templates for scaffolding new services, TechDocs for rendering documentation, and plugins that pull in data from CI/CD, cost tools, security scanners, and cloud providers, all inside one interface instead of a dozen disconnected tabs.
By 2026, Backstage has become close to a default choice for companies building an internal developer portal rather than buying one outright, and its plugin ecosystem has grown well beyond what Spotify originally shipped. Platform teams treat it as the presentation layer for their internal developer platform, the place where all the automation, guardrails, and self-service workflows a platform team builds become visible and usable to the rest of engineering. That matters because platform engineering as a discipline has grown specifically to address developer friction and cognitive load, and a portal without a catalog and a UI in front of it is much harder for engineers to actually use day to day. The rise of managed Backstage offerings from several vendors has also lowered the barrier to entry, letting mid-sized companies adopt the catalog model without hiring a dedicated team just to keep the underlying instance patched and running.
This page covers how Backstage is structured, why organizations adopt it, where it fits next to other platform engineering tools, and how teams that build a Backstage instance tend to succeed or stall. The durable idea underneath all of it is simple: a platform is only as good as its discoverability. If engineers cannot find what already exists, they will rebuild it, misconfigure it, or bypass it, and understanding Backstage gives a team the mental model to design a portal that developers will actually open every day instead of ignoring.
Everything in Backstage radiates outward from the catalog, and it's worth understanding that catalog as the actual point of the whole framework. Each entity, whether it's a service, a library, a website, a data pipeline, or a team, gets described in a `catalog-info.yaml` file that specifies its kind, its owner, its dependencies on other entities, and links to its docs, repo, and dashboards. That file usually lives in the same repository as the code it describes, which means updating ownership or dependency information is a pull request, not a separate documentation task that someone forgets to do. Backstage's entity model also supports systems, domains, and resources as distinct kinds, so a catalog can represent not just individual services but the larger groupings they belong to, which matters once an organization has hundreds of entities and needs a way to browse them by product area instead of scrolling one long flat list.
This approach solves a problem that documentation portals have struggled with for years: staleness. A wiki page about a service's ownership goes out of date the moment a reorg happens and nobody remembers to edit it. A catalog entry that lives in the repo and gets reviewed alongside code changes has a much better chance of staying accurate, because the people best positioned to notice it's wrong are the ones already touching the file.
The catalog also builds a dependency graph across the organization, not just a flat list. When Service A declares Service B as a dependency and Service B declares a database as a resource, Backstage can render that relationship visually and let anyone trace impact before a migration or a deprecation. That graph becomes genuinely useful for incident response, since responders can see immediately what depends on the service that just went down instead of guessing or paging around. It also helps with less urgent but still costly decisions, like planning a deprecation: an engineer can check the graph before shutting down an old internal library and see, in one view, every service that would break if they did.
None of this is automatic, though. The catalog is only as good as what gets registered into it, and organizations that treat catalog entries as optional metadata end up with a portal that lists half the services in the company and confuses people about whether the other half simply don't exist. Getting entities registered, usually through import tooling tied to the source control system, is the unglamorous work that makes or breaks the catalog. Some organizations solve this by requiring a valid `catalog-info.yaml` file as a condition of a repository passing CI, which turns registration from a voluntary best practice into an enforced gate, and tends to produce a far more complete catalog than relying on goodwill alone.
Backstage's software templates, often called the scaffolder, let a platform team define a golden path for creating a new service: a form that asks a few questions and then generates a repository with the right CI pipeline, the right base Dockerfile, the right observability hooks, and the right access policies already wired in. Instead of an engineer copying an existing service and manually stripping out what doesn't apply, they fill in a form and get a working, compliant starting point in minutes. A team might offer separate templates for a REST API, an event consumer, and a scheduled batch job, each encoding the specific conventions that kind of service needs, rather than one generic template that leaves engineers to work out the differences on their own.
This matters because the alternative, informal copy-paste from whatever repo looks similar, is how organizations end up with dozens of slightly different logging setups, inconsistent security defaults, and services that were never onboarded to the monitoring stack because nobody remembered that step. Templates encode the platform team's best practices directly into the creation process, so compliance with standards becomes the default outcome rather than something enforced after the fact through review or audit.
The templates are pluggable and can call out to other systems as part of the scaffolding process: creating a repository in GitHub or GitLab, registering a project in a CI system, provisioning a namespace, or opening a ticket for security review. That makes the scaffolder a genuine automation point, not just a code generator, because it can trigger the same steps a human would otherwise have to do by hand across several different tools.
The tradeoff is that templates require real maintenance. A template that generates a service using a deprecated base image or an old dependency version actively makes things worse, spreading an outdated pattern faster than manual copying would have. Platform teams that adopt Backstage templates need a process for reviewing and updating them on a cadence, the same way they would treat any other piece of shared infrastructure, and some teams assign a rotating owner specifically to audit templates each quarter so an outdated default doesn't quietly propagate for a year before anyone notices.
TechDocs is Backstage's built-in documentation system, and it takes an approach that deliberately differs from a wiki: documentation is written in Markdown, stored in the same repository as the code, and rendered into the portal automatically through a static site generator. The philosophy, sometimes called "docs like code," treats documentation as something that gets reviewed in pull requests alongside the code it describes, rather than edited separately in a tool most engineers only open when something is already broken. Because the raw Markdown sits in version control, an engineer can see the full history of how a piece of documentation changed over time, the same way they'd check the history of any source file, which is difficult or impossible with most standalone wiki tools.
Beyond TechDocs, the real extensibility of Backstage comes from its plugin architecture. Plugins are self-contained frontend and backend packages that add new capabilities: a plugin that shows Kubernetes pod status for a service, one that surfaces cost and cloud spend per team, one that pulls in security scan results, one that shows on-call schedules from an incident management tool. Each plugin registers itself into the shared navigation and can pull data through the catalog's entity references, so a service's page in Backstage can show its deploy status, its cost, its vulnerabilities, and its documentation side by side.
The Backstage community maintains an open plugin marketplace, and larger vendors in the cloud-native space, from cloud providers to CI/CD companies to security vendors, ship their own official plugins. That ecosystem is one of the main reasons companies choose Backstage over building a portal from scratch: rather than writing custom integrations for every tool in the stack, a team can often install and configure an existing plugin in a day. It's also why Backstage tends to win out over a homegrown internal tool once an organization's toolchain grows past a handful of systems; maintaining custom integrations for a dozen different tools in-house is a much larger ongoing burden than adopting plugins that a wider community already keeps updated.
Plugins are also where a lot of Backstage's maintenance burden concentrates. Each plugin has its own release cadence, its own breaking changes, and its own dependency on backend APIs that shift as Backstage itself evolves. A portal with forty plugins installed is a real piece of software with a real upgrade path, and organizations that skip that maintenance find their portal slowly falling out of sync with the tools it's supposed to represent. This is the same reason experienced platform teams resist installing every available plugin just because it exists; each one adds a specific, ongoing maintenance obligation, and a smaller set of plugins that are actually used and kept current beats a large set that half-work after a few missed upgrade cycles.
Backstage fits best in organizations with enough services, teams, and tooling sprawl that "who owns this and how do I use it" has become a recurring, costly question. That threshold tends to show up once a company has dozens of services and multiple independent teams, at which point informal channels like Slack messages and tribal memory stop scaling. Below that scale, a lightweight README convention and a shared wiki often does the job just as well without the overhead of running a portal. A useful gut check is to count how many times a week someone asks an ownership or discovery question in chat that a catalog would answer instantly; if that number is low, the organization probably isn't at the scale where Backstage pays for itself yet.
It's also worth being clear that Backstage is not itself a CI/CD system, an infrastructure provisioning tool, or a Kubernetes operator. It doesn't deploy anything on its own and it doesn't manage infrastructure state. It's a presentation and orchestration layer that calls out to the tools that already do those jobs, whether that's Crossplane or Terraform for infrastructure, Argo or Jenkins for delivery, or a service mesh for networking. Teams that expect Backstage to replace their platform automation instead of surface it end up disappointed.
Backstage also doesn't run itself. Someone has to own the instance: patch it, upgrade its dependencies, manage its plugins, and keep the catalog import pipeline healthy. That's a real operational cost, and companies that adopt Backstage without assigning a team to own it tend to end up with a portal that was impressive in a demo six months ago and has been quietly rotting since. The framework being open source and free doesn't mean running it is free; it means the licensing cost is zero and the engineering cost is entirely on the adopting team. In practice, that engineering cost usually amounts to a fraction of one or two platform engineers' time on an ongoing basis, which is modest compared to the cost of the manual coordination it replaces, but it is not zero and needs to be budgeted for honestly rather than assumed away.
For smaller companies or ones without a dedicated platform engineering function, a hosted Backstage-based product or a lighter internal developer portal tool is often a more realistic choice than standing up and maintaining Backstage from source. Several vendors now offer managed Backstage distributions specifically to remove that operational burden while keeping the open core and plugin compatibility, which has become a common middle path for teams that want the catalog model without hiring people to run the underlying infrastructure.
The adoption pattern that tends to work starts small and concrete rather than trying to model the entire organization on day one. Successful rollouts pick one real, painful problem, usually "nobody knows who owns what" or "creating a new service takes two weeks," and solve that narrowly before expanding the catalog to cover everything. A portal that launches with ten well-maintained entities and one working template beats one that launches with an ambitious plan to catalog four hundred services and stalls at sixty percent complete. Picking a single, visible pilot team to launch with first, ideally one with a genuine, well-known pain point, also gives the rest of the organization a concrete success story to point to instead of an abstract pitch about developer experience.
Getting entities into the catalog automatically, rather than asking engineers to write YAML by hand, is usually the difference between a catalog that stays current and one that decays within a quarter. Automated discovery that scans an organization's source control for a marker file, or that generates catalog entries from an existing service registry or CI system, removes the manual step that people deprioritize the moment there's a deadline. Manual registration works for a pilot; it does not survive contact with two hundred engineers. Some organizations go a step further and generate a starter `catalog-info.yaml` automatically as part of the scaffolder template itself, so any service created the "right" way is registered from birth and only services created outside the golden path ever need manual onboarding.
Ownership needs to be assigned early, both for the Backstage instance itself and for the catalog data quality inside it. Someone needs the authority to say a service must be registered before it goes to production, and someone needs to be accountable when the catalog starts drifting from reality. Without that ownership, Backstage tends to become an interesting side project that a few enthusiastic engineers maintain until they move to a different team, at which point it stagnates.
Measuring adoption matters too, and the metric that tends to correlate with real value is usage, not entity count. A catalog with a thousand entities that nobody opens is worse than a catalog with two hundred entities that engineers check every day before starting new work. Teams that track weekly active users of the portal, template usage rates, and how often engineers ask ownership questions in chat instead of checking the catalog get a much clearer signal on whether Backstage is actually solving the problem it was built for. It's worth reviewing these numbers on a regular cadence rather than once at launch, since a portal's usage can quietly decline months after a strong initial rollout if catalog data starts drifting or a popular plugin breaks and nobody notices for a while.
Backstage is an open source framework, created at Spotify and now hosted by the Cloud Native Computing Foundation, for building an internal developer portal that centers on a software catalog, service templates, and documentation, all extended through plugins.
The software itself is free and open source under an Apache 2.0 license, but running a Backstage instance takes real, ongoing engineering time for setup, integration, plugin maintenance, and upgrades, so the total cost is not zero even though there's no license fee to pay anyone.
Probably not yet. Backstage earns its cost once an organization has enough services and teams that finding ownership and documentation has become a recurring problem; a small team with a handful of services usually gets more value from a simple README convention.
The catalog is a structured inventory of every service, API, resource, and team in an organization, described through YAML metadata files that typically live in the same repository as the code, keeping ownership and dependency data close to where it changes.
A wiki stores documentation as pages that anyone can edit independently of the code, which tends to go stale. Backstage's catalog and TechDocs system tie metadata and documentation directly to the source repository, so they update as part of normal development instead of a separate task.
No. Backstage does not build, test, or deploy software on its own. It provides templates and plugins that can trigger and display information from your existing CI/CD system, but the pipeline itself still runs in whatever tool you already use, whether that's Jenkins, GitHub Actions, GitLab CI, or something else entirely.
Usually a platform engineering team owns the Backstage instance itself, including its plugins and upgrades, while individual service teams own the accuracy of their own catalog entries and documentation. In smaller organizations without a dedicated platform team, this ownership sometimes falls to a rotating group of senior engineers, but that arrangement tends to work only if someone is explicitly accountable rather than everyone assuming someone else is handling it.
Plugins are self-contained packages that add specific capabilities to a Backstage instance, such as showing deployment status, cost data, security scan results, or on-call schedules, and they integrate with the catalog so information appears alongside a service's entry.
Teams that start with a narrow, well-defined use case, such as one working template or an automated catalog import, often see engineers using the portal within weeks, while a full rollout covering documentation, templates, and dozens of plugins across an entire organization typically takes several months of ongoing work. The pace depends heavily on how much automated catalog discovery a team sets up early, since manual entity registration slows adoption considerably compared to pulling data in automatically from existing source control and CI systems. Teams that skip that automation and rely on engineers to hand-write catalog entries tend to see adoption stall well before the portal reaches enough coverage to be genuinely useful, which is why the catalog import pipeline deserves early investment even before the rest of the rollout is fully planned.
