Backstage Software Catalog Guide: Model Services, Ownership, and Lifecycle Metadata
BackstagePlatform EngineeringInternal Developer PortalsService CatalogDeveloper Experience

Backstage Software Catalog Guide: Model Services, Ownership, and Lifecycle Metadata

DDeployed.cloud Editorial Team
2026-11-17
9 min read

A practical Backstage catalog guide covering entity YAML, ownership, dependencies, scorecards, lifecycle metadata, and recurring cleanup.

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.yaml file.
  • 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 as service, website, library, or job.
  • spec.lifecycle: a controlled value such as experimental, production, deprecated, or another lifecycle vocabulary defined by your organization.
  • spec.owner: a reference to a group or, only where appropriate, an individual.
  • spec.system or spec.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

FieldPurposeReview question
apiVersionIdentifies the entity schema version.Does it match the schema supported by this Backstage installation?
kindDefines the entity type.Is this really a component, API, resource, system, or another supported kind?
metadata.nameProvides the stable entity identifier.Is it unique, readable, and unlikely to change?
metadata.annotationsConnects the entity to tools and external locations.Are annotations supported, accurate, and free of secrets?
spec.ownerIdentifies the accountable group or user.Can that owner respond to an operational or catalog question?
spec.lifecycleCommunicates the service’s current stage.Is the value from the approved vocabulary?
spec.dependsOnDocuments 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:

  1. Export or query entities with missing owners, invalid relations, failed processing, and stale review dates.
  2. Sample healthy and unhealthy records from each major team, repository type, and deployment model.
  3. Ask owners to confirm lifecycle, dependencies, support links, and retirement status.
  4. Remove or archive entities only after confirming that the underlying service, repository, or resource is no longer needed.
  5. Review one or two scorecard rules for false positives and unclear remediation steps.
  6. Update templates and documentation when the approved YAML shape or onboarding workflow changes.
  7. 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.

Related Topics

#Backstage#Platform Engineering#Internal Developer Portals#Service Catalog#Developer Experience
D

Deployed.cloud Editorial Team

Platform Engineering Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.