Adopting Backstage to centralize an organization’s service discovery solves a real problem (knowing who owns what, where to find documentation, a service’s production status), but the value of that centralization depends entirely on how fresh the catalog data stays, an organizational problem far more than a tooling one.

What Backstage actually centralizes

Backstage aggregates each service’s metadata (owner, dependencies, documentation links, production status) from a catalog-info.yaml file committed to each service’s repository, rather than discovering that information dynamically from the infrastructure itself.

# catalog-info.yaml: the catalog's source of truth,
# manually maintained in each service's repository
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: Handles payments and refunds
spec:
  type: service
  owner: team-payments
  lifecycle: production

The trap: a declarative source of truth, not an observed one

Unlike a system that would query the infrastructure directly in real time (Kubernetes, a container registry), the Backstage catalog reflects whatever a YAML file declares, not what’s actually running in production. A service whose owning team changed, whose status moved from “experimental” to “production,” or that was simply decommissioned keeps showing up in the catalog exactly as before, as long as nobody manually updates its catalog-info.yaml.

Why this drift almost always happens

Initial Backstage adoption typically produces an up-to-date catalog, each team filling in its catalog-info.yaml at platform rollout time. The problem shows up afterward: without an explicit process (a CI check, a periodic review), keeping the catalog current stays an optional task nobody prioritizes over production emergencies. That’s exactly the problem continuous reconciliation solves on the infrastructure side (a controller constantly checks that real state matches declared state): Backstage, on the other hand, reconciles nothing automatically, the catalog staying frozen on whatever was written once into catalog-info.yaml.

The fix: treating the catalog as code validated in CI

The practice that actually limits this drift is validating catalog-info.yaml in CI just like any other configuration file (schema respected, owner matching an actual existing team), and failing a PR that introduces a service with no matching catalog entry, rather than relying on teams’ goodwill to keep the catalog current after the fact.

Takeaway

Backstage centralizes service discovery from a declarative file (catalog-info.yaml), not real-time infrastructure observation: its value depends entirely on how fresh that file stays, never guaranteed by the tool itself. Without an explicit verification process, the catalog silently drifts from reality, an adoption trap more common than any technical Backstage issue. Validating the catalog in CI, exactly like any other versioned configuration, is the only practice that actually prevents this drift from taking hold.