In a large engineering organisation, simple questions are surprisingly hard to answer. Who owns this service? Where are its docs? Which version is in production? What does it depend on? How do I create a new service the "right" way?
The answers are usually spread across wikis, spreadsheets, CI systems, cloud consoles and people's heads. An internal developer portal brings them into one place. And for many organisations, that portal is built on Backstage.
Where Backstage came from
Spotify built Backstage internally to manage a fast-growing microservice estate, and open-sourced it in March 2020. It joined the CNCF as a sandbox project later that year and was promoted to incubating status in March 2022. It is now one of the CNCF's most active projects, with a large plugin ecosystem and commercial offerings built around it.
The core features
Software catalogue
The catalogue is the heart of Backstage. It tracks components (services, websites, libraries), APIs, resources (databases, buckets), systems that group them, and the teams that own them.
Entries are defined by YAML files that live in each component's repository:
# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: invoice-api
description: Creates and serves customer invoices
annotations:
github.com/project-slug: example/invoice-api
backstage.io/techdocs-ref: dir:.
pagerduty.com/service-id: P1234AB
tags: [java, billing]
spec:
type: service
lifecycle: production
owner: team-billing
system: billing
providesApis: [invoice-api-v2]
dependsOn: [resource:invoices-db]Because the metadata lives with the code, it is versioned, reviewed and much more likely to stay current than a separate spreadsheet.
Software templates
Templates turn golden paths into self-service. A developer fills in a short form, and Backstage creates a repository, CI pipeline, catalogue entry and whatever else the template defines:
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: java-service
title: Java REST service
spec:
owner: platform-team
parameters:
- title: Service details
required: [name, owner]
properties:
name: { type: string }
owner: { type: string, ui:field: OwnerPicker }
steps:
- id: fetch
action: fetch:template
input: { url: ./skeleton, values: { name: "${{ parameters.name }}" } }
- id: publish
action: publish:github
input: { repoUrl: "github.com?owner=example&repo=${{ parameters.name }}" }
- id: register
action: catalog:register
input: { repoContentsUrl: "${{ steps.publish.output.repoContentsUrl }}", catalogInfoPath: /catalog-info.yaml }TechDocs
A "docs-like-code" system: Markdown documentation in each repository is built with MkDocs and published alongside the catalogue entry, so the docs for a service are one click away from its owner, APIs and deployments.
Plugins
Most of Backstage's value comes from plugins that surface information from other tools on each component's page: CI status, Kubernetes deployments, incidents and on-call, cost, security findings, API documentation and more. Organisations also write their own plugins for internal systems.
What a portal is (and is not) for
A portal is the front door to your platform, not the platform itself. If creating a database still needs a ticket behind the scenes, a Backstage form in front of that ticket is only a small improvement. The biggest benefits come when the portal fronts genuine self-service capabilities built by your platform team.
Good early use cases:
- a trustworthy catalogue with ownership for every service,
- one or two excellent templates for the most common workloads, and
- docs, CI and deployment status visible in one place.
What it takes to run Backstage
Backstage is a framework: a React and Node.js application that you assemble, configure, extend and host yourself. That flexibility is powerful, but it has costs:
- Engineering effort. Teams typically need at least one or two engineers who own the portal, handle upgrades (Backstage releases frequently) and build plugins.
- Catalogue quality. The portal is only as useful as its data. You need processes, and ideally automation, to make sure components are registered and owners are correct.
- Adoption. Developers need a reason to visit. Make it the fastest way to answer everyday questions.
If that engineering investment is not realistic, managed Backstage services and commercial portals offer similar capabilities with less effort.
Security and governance benefits
A good catalogue is also a security asset:
- Ownership: when a vulnerability is found, you know which team to contact.
- Inventory: it complements SBOMs and cloud inventories with the human context of what a component does and who owns it.
- Scorecards: plugins can show whether each service meets standards such as having an owner, being on a supported runtime, having no critical vulnerabilities and having on-call configured.
The bottom line
Backstage has become the de facto standard framework for developer portals because it tackles a real problem, fragmented knowledge about software, with an extensible, open approach. Treat it as a product that sits on top of real self-service capabilities, invest in the catalogue data, and it becomes the place where your engineering organisation finds its way.
Our secure SDLC and DevSecOps teams build developer portals and the platform capabilities behind them.