A useful Backstage software catalog is more than a directory of repositories: it is a maintained record of what a team owns, how services relate, which lifecycle stage they occupy, and what operational standards they meet. This guide provides a repeatable workflow for designing Backstage entity metadata, registering services, assigning ownership, modeling dependencies, adding scorecards, and reviewing stale records on a monthly or quarterly cadence.
Overview
Backstage works best when the catalog answers practical questions quickly: Who owns this service? Where is its source code? Which system does it belong to? Is it experimental, production, or deprecated? What does it depend on? Which standards still need attention?
The platform team should treat the catalog as an internal API for developer and operational information. Teams consume that information through the Backstage interface, templates, plugins, search, ownership views, and automation. That makes metadata quality more important than simply increasing the number of registered entities.
A sensible operating model has four characteristics:
- Ownership is explicit. Every production component has a responsible group, not merely an individual who may change roles.
- Metadata has a source of truth. Whenever possible, service metadata is stored with the repository in a reviewed
catalog-info.yamlfile. - Relationships are useful. Dependencies, systems, APIs, resources, and domains are modeled only when they support discovery, ownership, or operations.
- Staleness is managed. Catalog records have review signals and an escalation path rather than being assumed to remain accurate indefinitely.
Backstage behavior can vary with the release, installed plugins, catalog processors, authentication configuration, and organization-specific conventions. Before changing production configuration, check the documentation and examples that match the Backstage version and plugins you operate. Treat this guide as a design and review workflow, not as a substitute for version-specific configuration reference.
What to track
1. Define a small entity model
Start with the entity kinds your platform team can maintain. Many catalogs begin with Component, API, Resource, System, Domain, Group, and User. You do not need to model every organizational concept on the first day.
Use Domain for a business or capability area, System for a collection of related components and resources, and Component for a deployable or maintainable software unit. Add API when an interface needs to be discoverable, and Resource for infrastructure or supporting services that teams depend on. Keep the distinction consistent: a database used by several services is usually a resource, while the application connecting to it is a component.
2. Establish required metadata
Agree on required fields before onboarding dozens of repositories. A practical baseline for a component includes:
metadata.name: a stable, lowercase identifier that is easy to use in URLs and references.metadata.description: a concise explanation of the service’s purpose and users.metadata.tags: controlled terms such as language, runtime, or business capability. Avoid uncontrolled tag growth.metadata.annotations: integration-specific values, such as repository, deployment, documentation, or monitoring references.spec.type: a consistent category such asservice,website,library, orjob.spec.lifecycle: a controlled value such asexperimental,production,deprecated, or another lifecycle vocabulary defined by your organization.spec.owner: a reference to a group or, only where appropriate, an individual.spec.systemorspec.subcomponentOf: a relationship that places the component in context.
Do not overload descriptions or annotations with fields that should be modeled as relations. For example, a dependency is easier to query and review when represented in spec.dependsOn rather than buried in free text.
3. Use a repository-owned entity file
A typical component declaration might look like this:
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payments-api
description: Handles payment authorization for the checkout system.
tags:
- nodejs
- http-api
annotations:
backstage.io/source-location: url:https://git.example.com/payments/payments-api
backstage.io/techdocs-ref: dir:.
spec:
type: service
lifecycle: production
owner: group:payments
system: commerce
dependsOn:
- resource:default/payments-db
- component:default/fraud-check
providesApis:
- payments-api
The exact annotations supported by your installation depend on Backstage and its plugins. Use the annotation conventions documented by your configured integrations, and validate URLs, namespaces, and entity references before merging. A repository file should be reviewed like application configuration: changes to ownership, lifecycle, or dependencies deserve an accountable reviewer.
4. Register locations deliberately
Registration tells the catalog where to find entity definitions. A platform team can register individual locations, integrate repository discovery, or use an approved self-service template that creates both a repository file and its catalog registration. The right choice depends on repository count, access controls, and how much automation your team can support.
Do not make registration an unrestricted way to ingest arbitrary YAML. Define who can register locations, which repository hosts are allowed, how ownership is established, and how a location can be removed. Review catalog ingestion permissions alongside the catalog configuration and authentication setup after Backstage upgrades.
5. Model ownership and dependencies
Prefer group ownership for services that require ongoing support. Group references should follow one convention, for example group:payments or group:default/payments, rather than mixing formats without a reason. Make the owner responsible for keeping the record accurate, while the platform team owns the catalog rules and tooling.
Use relations such as dependsOn, ownedBy, partOf, providesApis, and consumesApis to expose architecture. Add a relation only when somebody will use it—for troubleshooting, impact analysis, onboarding, or change review. A large graph filled with guessed dependencies is less useful than a smaller graph backed by repository configuration, deployment manifests, or team confirmation.
6. Track lifecycle and operational signals
Lifecycle metadata should describe the service’s stage, not its quality. A production service can still need security or reliability work; a deprecated service may still require an owner until it is removed. Consider adding organization-specific metadata for:
- last ownership review date;
- deprecation or retirement target;
- criticality or business impact classification;
- support channel and escalation documentation;
- runbook, dashboard, alert, and incident-management links;
- data classification or compliance review status, where your governance model requires it.
Keep these fields controlled and documented. If a field cannot be updated reliably, it should not be presented as authoritative.
Catalog YAML reference
| Field | Purpose | Review question |
|---|---|---|
apiVersion | Identifies the entity schema version. | Does it match the schema supported by this Backstage installation? |
kind | Defines the entity type. | Is this really a component, API, resource, system, or another supported kind? |
metadata.name | Provides the stable entity identifier. | Is it unique, readable, and unlikely to change? |
metadata.annotations | Connects the entity to tools and external locations. | Are annotations supported, accurate, and free of secrets? |
spec.owner | Identifies the accountable group or user. | Can that owner respond to an operational or catalog question? |
spec.lifecycle | Communicates the service’s current stage. | Is the value from the approved vocabulary? |
spec.dependsOn | Documents technical dependencies. | Would this relation help assess change or incident impact? |
Cadence and checkpoints
Catalog maintenance should be part of platform operations rather than an occasional cleanup project. Use a monthly review for high-change areas and a quarterly review for the wider catalog. The cadence can be adjusted to match repository volume, release frequency, and the consequences of stale ownership.
Monthly checks
- Find components with missing owners, invalid relations, or failed catalog processing.
- Review new repositories and recently created entities for naming and metadata consistency.
- Check that links to source, documentation, dashboards, and runbooks still resolve.
- Compare recent deployment or repository activity with lifecycle values.
- Review changes to groups and users from the authoritative identity source.
Quarterly checks
- Ask each owning group to confirm its production components and critical dependencies.
- Audit deprecated or experimental services for a retirement, promotion, or ownership decision.
- Review entity kinds, required fields, controlled vocabularies, and custom annotations.
- Evaluate catalog plugins and processors for compatibility with the Backstage version in use.
- Inspect scorecard rules to ensure they measure actionable standards rather than producing noise.
Record the review date and outcome in a system teams already use for work tracking. A simple queue of exceptions is often more effective than asking every team to rewrite catalog files on a fixed schedule.
How to interpret changes
A rising count of catalog entities is not automatically progress. Interpret changes by asking whether discovery, ownership, and operational response have improved.
More entities with more processing errors usually indicates that ingestion is outpacing validation. Pause expansion, identify the common schema or permission failure, and improve the registration path before onboarding more repositories.
Many components with no recent owner confirmation signals a governance problem, not necessarily team neglect. Ownership may be stored in a different system, group synchronization may be failing, or the review request may lack a clear action. Fix the workflow and escalation route before adding more mandatory fields.
A sharp increase in dependencies may reflect better visibility, but it can also result from a processor or template change that creates duplicate or overly broad relations. Sample records before treating the trend as an architecture change.
Low scorecard completion should lead to investigation. A missing runbook may be a genuine reliability gap, but it may also mean the plugin cannot find the expected annotation or the team uses a different documentation location. Separate data-quality failures from standard failures.
Scorecards are most useful when they are small, explainable, and linked to an owner. Examples include a valid owner, source repository, support documentation, deployment reference, and an operational dashboard for services that require one. Avoid presenting a score as a universal measure of engineering quality.
For production services, connect catalog metadata to the wider platform workflow. Kubernetes deployment reviews, image-signing controls, OpenTelemetry instrumentation, and GitOps checks can each link back to the owning entity. For related operational guidance, see the Kubernetes deployment best practices checklist, the software supply chain security guide, and the OpenTelemetry setup guide.
When to revisit
Revisit the catalog design immediately after a Backstage upgrade, a major plugin change, an identity-provider migration, or a change to repository hosting. These events can affect entity schemas, processor behavior, annotations, template syntax, authentication, and catalog permissions. Validate a representative set of entities in a non-production environment before applying configuration changes broadly.
Use the following practical checklist for each monthly or quarterly review:
- Export or query entities with missing owners, invalid relations, failed processing, and stale review dates.
- Sample healthy and unhealthy records from each major team, repository type, and deployment model.
- Ask owners to confirm lifecycle, dependencies, support links, and retirement status.
- Remove or archive entities only after confirming that the underlying service, repository, or resource is no longer needed.
- Review one or two scorecard rules for false positives and unclear remediation steps.
- Update templates and documentation when the approved YAML shape or onboarding workflow changes.
- Record unresolved exceptions with an owner and a next review date.
When a service is deprecated, keep its record long enough to communicate the owner, replacement, retirement date, and remaining dependencies. After retirement, follow your organization’s retention and audit requirements before removing the entity. A catalog that explains what disappeared can be as valuable as one that lists what is new.
The most effective Backstage software catalog is maintained as part of normal engineering work: repository changes update metadata, templates create valid defaults, processors expose errors, and recurring reviews close the gaps. Start with a small entity model, make ownership unambiguous, measure only useful standards, and return to the catalog whenever the platform or service landscape changes.