Backstage and the Service Catalog

1. 1

   Create the app

   The generator creates a monorepo with packages/app (frontend) and packages/backend. It runs with SQLite in memory locally; production uses PostgreSQL (and runs as a container in your cluster, deployed through GitOps like any other service).

   terminalcopy cmd

   $ npx @backstage/create-app@latest --path shoplite-portal

   cd shoplite-portal && yarn start

   ── expected output ──

   Successfully created shoplite-portal

   ...

   [0] webpack compiled successfully

   [1] Listening on :7007

   App available at http://localhost:3000

2. 2

   Describe the organisation

   Teams and people. In production these are synced from GitHub teams, Okta, or Entra ID with an org provider; a static file is fine to start.

   apiVersion: backstage.io/v1alpha1
   kind: Group
   metadata: { name: team-checkout, title: Checkout Team }
   spec:
     type: team
     profile: { email: checkout@shoplite.dev }
     children: []
     members: [asha, ravi]
   ---
   apiVersion: backstage.io/v1alpha1
   kind: Group
   metadata: { name: team-platform, title: Platform Team }
   spec: { type: team, children: [], members: [mei] }
   ---
   apiVersion: backstage.io/v1alpha1
   kind: User
   metadata: { name: asha }
   spec: { profile: { displayName: Asha Rao, email: asha@shoplite.dev }, memberOf: [team-checkout] }

3. 3

   Describe a service where its code lives

   Each repo carries its own catalog-info.yaml, so the team that owns the code maintains its metadata in the same PR as code changes. Annotations connect plugins: which GitHub repo, which Kubernetes label selects its pods, which Argo CD app deploys it, and where its docs live.

   apiVersion: backstage.io/v1alpha1
   kind: Component
   metadata:
     name: checkout-api
     description: Takes carts to paid orders.
     tags: [java, spring-boot]
     links:
       - { url: https://grafana.shoplite.dev/d/checkout, title: Dashboard, icon: dashboard }
       - { url: https://runbooks.shoplite.dev/checkout, title: Runbook }
     annotations:
       github.com/project-slug: shoplite/checkout-api
       backstage.io/kubernetes-label-selector: app=checkout
       argocd/app-selector: service=checkout
       backstage.io/techdocs-ref: dir:.
   spec:
     type: service
     lifecycle: production
     owner: group:team-checkout
     system: checkout
     providesApis: [checkout-v1, order-events]
     consumesApis: [catalog-v2]
     dependsOn: [resource:checkout-db]
   ---
   apiVersion: backstage.io/v1alpha1
   kind: API
   metadata: { name: checkout-v1 }
   spec:
     type: openapi
     lifecycle: production
     owner: group:team-checkout
     system: checkout
     definition:
       $text: ./openapi.yaml
   ---
   apiVersion: backstage.io/v1alpha1
   kind: Resource
   metadata: { name: checkout-db, description: Checkout PostgreSQL (RDS) }
   spec: { type: database, owner: group:team-checkout, system: checkout }

4. 4

   Discover every repo automatically

   Instead of registering files one by one, the GitHub discovery provider scans the organisation for catalog-info.yaml files on a schedule. Install @backstage/plugin-catalog-backend-module-github in the backend (backend.add(import('@backstage/plugin-catalog-backend-module-github'))) and configure it. A GitHub App (not a personal token) gives it read access.

   integrations:
     github:
       - host: github.com
         apps:
           - $include: github-app-credentials.yaml   # from a Kubernetes Secret in production
   
   catalog:
     rules:
       - allow: [Component, System, API, Resource, Location, Group, User, Domain, Template]
     locations:
       - { type: file, target: ../../catalog/org.yaml }
       - { type: file, target: ../../catalog/systems.yaml }
     providers:
       github:
         shoplite:
           organization: shoplite
           catalogPath: /catalog-info.yaml
           filters: { branch: main }
           schedule: { frequency: { minutes: 30 }, timeout: { minutes: 3 } }

   terminalcopy cmd

   $ yarn start

   # then open http://localhost:3000/catalog?filters[kind]=component

   ── expected output ──

   [1] catalog info Read 23 GitHub repositories (14 matching the pattern) type=plugin target=github-provider:shoplite

   [1] catalog info Committed 41 entities for github-provider:shoplite

Make each change, run the command, and read the error before revealing the diagnosis. Recognising these messages on sight is what makes you fast on a real team. Undo the change afterwards.