Skip to main content
Backstage Software Catalog: Getting Adoption Past the Demo

Backstage Software Catalog: Getting Adoption Past the Demo

KU
· Founder & Chief Editor
• 6 min read•Updated •38 views

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.

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.

app-config.yaml
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:

payments-service/catalog-info.yaml
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):

TypeScript
// 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

Explore topics:Infrastructure
React
Share this post
Cite this article
Plain text

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

Markdown

[Backstage Software Catalog: Getting Adoption Past the Demo](https://www.devopsness.com/blog/backstage-software-catalog-adoption) (Kiril Urbonas, DevOpsNess, updated 2026-10-31)

KU

Kiril Urbonas

Founder & Chief Editor

605 articles
View all articles by Kiril Urbonas

You might have missed

Evergreen posts worth revisiting.