Backstage Software Catalog: Getting Adoption Past the Demo
The Backstage demo always wows leadership. Then six months later the catalog has 400 stale entries and nobody trusts it. Here's what got ours to actually stick.
Key takeaways
- A Backstage catalog gets adopted when its data is trustworthy without manual upkeep.
- Auto-discover catalog-info.yaml files from GitHub, fail CI on any component without a valid owner, host TechDocs inside Backstage, and add scorecards leadership reviews.
- Manual registration produces a stale catalog that engineers stop opening within months.
On this page
Backstage catalog adoption sticks when nobody has to type what a machine can discover. Turn on the GitHub entity provider so catalog-info.yaml files are found automatically, fail CI on components without a real owner, put TechDocs inside Backstage, and publish scorecards leadership reads. Ask teams to register services by hand and the catalog goes stale within a quarter.
Verified against
Backstage 1.56.2, @backstage-community/plugin-tech-insights 1.5.0, against the backstage.io GitHub discovery, descriptor format and TechDocs docs. Checked October 2026.
Our first Backstage rollout died quietly. We stood it up, ran a demo that made VPs nod, and asked every team to register their services by hand. Three weeks in we had a few dozen entries, half of them misspelled. By month three the catalog listed services that had been decommissioned, owners who'd left the company, and docs links that 404'd. Engineers stopped opening it, which meant they stopped maintaining it, which meant it got worse. The catalog was a graveyard.
The relaunch worked, and the difference came down to that one rule.
Stop asking people to register services
Manual catalog-info.yaml registration is where adoption goes to die. Nobody remembers to add a new service, and nobody remembers to delete an old one. We switched to auto-discovery against our GitHub org so the catalog reflects reality without anyone thinking about it.
catalog:
providers:
github:
devopsnessOrg:
organization: 'devopsness'
catalogPath: '/catalog-info.yaml'
filters:
branch: 'main'
repository: '.*-service$'
schedule:
frequency: { minutes: 30 }
timeout: { minutes: 3 }
Repos that match *-service get scanned every 30 minutes. A deleted repo drops out of the catalog on the next sweep. That single change killed the stale-entry problem that had sunk the first attempt.
Make the entity file trivial to get right
Even with discovery, each repo needs a catalog-info.yaml. If that file is hard to write, teams will half-fill it. We kept the required surface tiny and generated it inside our service scaffolder, the template behind our golden path, so new repos ship with it already correct:
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payments-service
annotations:
github.com/project-slug: devopsness/payments-service
pagerduty.com/service-id: PD5X8Q2
backstage.io/techdocs-ref: dir:.
spec:
type: service
lifecycle: production
owner: team-payments
system: checkout
Backstage's descriptor format already makes spec.owner, spec.type and spec.lifecycle required for a Component; system is optional. The owner field is the one that matters, and we made it non-negotiable beyond the schema. A component with no valid owner, or an owner that doesn't map to a real group in the org, fails a CI check. No ownerless services in the catalog, ever. That's how you keep the "who do I ask about this" question answerable, which is the whole reason people open the catalog in the first place.
Give people a reason to look
Discovery keeps the catalog honest, but honesty isn't a reason to visit. We added a Soundcheck-style scorecard (you can build a lighter version with the open-source @backstage-community/plugin-tech-insights frontend and its -backend package, 1.5.0 and 3.1.0 as of October 2026) that grades every service on things people already argue about: has a README, has an on-call rotation wired up, ran a deploy in the last 30 days, has no critical CVEs open past SLA.
This is a sketch of the check logic, not the plugin's exact API (its default checker evaluates JSON rules against collected facts):
// sketch: recent-deploy check
export const hasRecentDeploy: FactChecker = {
id: 'recent-deploy',
name: 'Deployed in last 30 days',
factIds: ['deploy.lastTimestamp'],
rule: (facts) => {
const days = (Date.now() - facts['deploy.lastTimestamp']) / 86400000;
return { result: days <= 30, value: days };
},
};
Once a director could pull up a table showing which teams had services failing the security check, the catalog stopped being optional. Engineers checked their own scorecard before their manager did. Adoption stopped being something we pushed and became something people self-served.
The number that predicted success
The metric we watched wasn't entry count, it was weekly active catalog users divided by engineers. At launch it was in the single digits, which is demo-only territory. It passed half of engineering once TechDocs went live inside Backstage, because now the catalog was where the runbooks lived. People came for docs and stayed for everything else. If your docs are still in a separate wiki, the catalog will always be a second stop, and second stops get skipped.
What we'd skip next time
We spent two weeks building a custom plugin to visualize service dependencies. It looked great in the demo and nobody used it. The dependency graph is only useful during an incident, and during an incident people go to the runbook, not a graph. Build the boring things first: discovery, ownership enforcement, docs, scorecards. Save the pretty graph for after people already trust the data.
Questions people ask
Why do Backstage catalogs go stale?
Because they depend on people remembering to register new services and delete dead ones, and nobody does either reliably. Owners leave, repos get archived, docs links rot, and engineers who hit bad data stop opening the catalog. Automated discovery fixes most of it: the GitHub provider rescans on a schedule, so archived or deleted repos drop out and new ones appear without anyone filing a ticket.
How do you measure Backstage adoption?
Track weekly active catalog users divided by total engineers, not the number of entities. Entity count rises with auto-discovery whether or not anyone uses the catalog. The active-user ratio shows whether engineers come back on their own. In our experience it moves most when the catalog becomes the place for something people need daily, such as runbooks in TechDocs or on-call ownership.
Do you need Soundcheck for Backstage scorecards?
No. Soundcheck is Spotify's commercial plugin, but the open-source Tech Insights plugins from the Backstage community repository collect facts about each entity and run checks against them. That covers the basics: README present, on-call wired up, recent deploy, no overdue CVEs. Buy Soundcheck if you want its UI and campaign features; start with Tech Insights if you only need pass or fail checks.
The call we'd make
Backstage lives or dies on trust in the data, and trust comes from automation, not diligence. Auto-discover everything, enforce ownership in CI, put your docs inside it, and add a scorecard leadership actually looks at. If you're relying on engineers to manually register and update services, cancel the project now and save yourself the graveyard. Ours went from a few dozen rotting entries to an accurate catalog of every service once we stopped asking humans to do a robot's job.
Before you invest this much in the catalog, check whether Backstage is even the right call for your team size in the first place: see internal developer platforms: is Backstage worth it?
Sources
Cite this article
Kiril Urbonas (2026). Backstage Software Catalog: Getting Adoption Past the Demo. DevOpsNess. Updated 2026-10-31. https://www.devopsness.com/blog/backstage-software-catalog-adoption
[Backstage Software Catalog: Getting Adoption Past the Demo](https://www.devopsness.com/blog/backstage-software-catalog-adoption) (Kiril Urbonas, DevOpsNess, updated 2026-10-31)
More from Infrastructure
Explore more articles in this category
TCP vs UDP: What's the Difference?
A practical look at how TCP and UDP trade reliability for speed, and how to pick the right one for your service.
Multi-Cloud Infrastructure: Managing Resources Across Providers
We run mostly on AWS but use GCP for specific workloads. The honest cost-benefit analysis of multi-cloud, plus the patterns that make it not awful.
Ansible Playbook Optimization: Writing Efficient Playbooks
We cut our largest playbook's runtime from 14 minutes to 4 minutes. The specific changes that mattered, plus the ones that didn't.
You might have missed
Evergreen posts worth revisiting.