Building an Internal Software Catalog with Backstage

Description and use

Backstage’s internal catalog accelerated service discovery, clarified ownership, and streamlined onboarding, delivering measurable business impact.

Problem

Developers cannot quickly locate services, libraries, or documentation, leading to duplicated work, slow onboarding, and delayed incident response.

Outcome

The catalog enabled immediate discoverability, reduced duplicate work, clarified ownership, and accelerated onboarding, while providing metrics for adoption and business impact.

Workflow

• Define minimal catalog-info.yaml schema with required fields (name, description, tags, owner, type, lifecycle).
• Create a scaffolder template that generates a new repo with catalog-info.yaml, README, TechDocs stub, and CI pipeline.
• Configure app-config.yaml integrations for GitHub (or other hosts) to enable discovery providers and schedule scans.
• Set up automated catalog health jobs to flag missing owners, stale lifecycles, or failing CI and notify via Slack.
• Enforce governance rules: require catalog-info.yaml for production services, allow lighter rules for libraries, and establish trusted committer roles.

Evidence

Every time a developer can’t find the service they need, work halts.

Source

Backstage’s Software Catalog is built precisely for that purpose: it centralizes metadata about services, libraries, APIs, docs, and teams so discovery becomes a first‑class developer action rather than an archaeological dig.

Source

Provide a scaffolder template that creates the repo with a catalog-info.yaml, README.md, TechDocs stub, and a CI pipeline.

Source

Use scheduled discovery providers (GitHub Discovery, GitLab Discovery) to re‑scan repositories for descriptor changes.

Source