Demo Registering a Component

In this lesson we’ll walk through registering your first real component in Backstage. You’ll learn where Backstage loads example entities from, how to register a local component, how to import a catalog-info.yaml from a remote Git repository, and how to refresh or unregister entities from the Catalog.

Where the examples come from

A newly provisioned Backstage instance includes example entities imported via the backend configuration (app-config.yaml). At the top of the config you typically have base URLs:

app:
  baseUrl: http://147.182.170.10:3000

backend:
  baseUrl: http://147.182.170.10:7007

cors:
  origin: http://147.182.170.10:3000

Search for the catalog section to find static imports (locations). Files referenced with type: file are resolved relative to the backend process (usually packages/backend):

catalog:
  import:
    entityFilename: catalog-info.yaml
    pullRequestBranchName: backstage-integration
  rules:
    - allow: [Component, System, API, Resource, Location]
  locations:
    # Local example data, file locations are relative to the backend process, typically `packages/backend`
    - type: file
      target: ../../examples/Entities.yaml

    # Local example template
    - type: file
      target: ../../examples/template/template.yaml
      rules:
        - allow: [Template]

Follow the relative path to examples/Entities.yaml and you’ll find example entities such as an example-website component and an example API:

# examples/Entities.yaml (excerpt)
owner: guests
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: example-website
spec:
  type: website
  lifecycle: experimental
  owner: guests
  system: examples
  providesApis: [example-grpc-api]
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: example-grpc-api
spec:
  type: grpc
  lifecycle: experimental
  owner: guests
  system: examples
  definition: |
    syntax = "proto3";

This is why the Catalog UI shows example components — they are imported from that file.

Registering a real component (auth service)

Below is a minimal Node.js Express service that we’ll register with Backstage:

import express from "express";

const app = express();

app.get("/", (req, res) => {
  res.send("Hello World!");
});

const port = 3000;
app.listen(port, () => {
  console.log(`Example app listening on port ${port}`);
});

To register this service, create a catalog-info.yaml at the root of your project describing the component. The required fields are apiVersion, kind, metadata, and spec. Example:

apiVersion: backstage.io/v1beta1
kind: Component
metadata:
  name: auth-service
  description: authentication service
  tags:
    - javascript
  links:
    - url: https://google.com
      title: Admin Dashboard
      icon: dashboard
      type: admin-dashboard
spec:
  type: service
  lifecycle: production
  owner: guests

Notes:

spec.type is a free-form string; teams should agree on a consistent taxonomy (e.g., service, website, library) so catalog browsing and filtering remain useful.
owner should point to an existing user or group entity in the Catalog. The default Backstage instance includes example entities such as guest and guests; this is why guests works in examples.

When the auth component is present in the Catalog, Backstage displays its metadata (owner, type, lifecycle, tags, and links):

A screenshot of the Backstage "My Company Catalog" web UI showing a table of two components (auth-service and example-website) with columns for owner, type, lifecycle, and tags. The page includes a left navigation sidebar, filters on the left, and a "CREATE" button plus a search field.

Four common ways to import a component into Backstage

Static import from the Backstage repository (local file)
Static import from a URL (e.g., a catalog-info.yaml stored on GitHub)
Register via the Backstage UI (Register Existing Component)
Automatic registration via templates or repository-scanning integrations

A concise overview:

Method	When to use	Example
Local `file` import	For local/backstage-repo-driven demos or self-hosted examples	Add `- type: file` with `target: ../../examples/auth-entity.yaml` in `app-config.yaml`
Remote `url` import	When `catalog-info.yaml` lives with your source code in a repo	Add `- type: url` with `target: https://github.com/you/repo/blob/main/catalog-info.yaml`
UI registration	Quick one-off imports without editing backend config	Use “Register Existing Component” in Backstage and paste the `catalog-info.yaml` URL
Templates / integrations	For automated at-scale registration across many repos	Use scaffolding templates or code host scanning/integrations

Static import (local file)

Save your catalog-info.yaml as a local entity file, for example examples/auth-entity.yaml.
Add a file location to app-config.yaml (paths are relative to packages/backend):

catalog:
  import:
    entityFilename: catalog-info.yaml
    pullRequestBranchName: backstage-integration
  rules:
    - allow: [Component, System, API, Resource, Location]
  locations:
    - type: file
      target: ../../examples/Entities.yaml

    - type: file
      target: ../../examples/auth-entity.yaml

    - type: file
      target: ../../examples/template/template.yaml
      rules:
        - allow: [Template]

Restart the Backstage backend (or yarn dev in development). After the backend restarts, the new component should appear in the Catalog.

Static import (from GitHub)

A common pattern is to keep catalog-info.yaml in the same repository as the service and let Backstage import it via URL. Example Git commands to push your project to GitHub:

echo "# backstage-auth-service" >> README.md
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/Sanjeev-Thiyagarajan/backstage-auth-service.git
git push -u origin main

Add the remote catalog-info.yaml as a url location in app-config.yaml:

catalog:
  import:
    entityFilename: catalog-info.yaml
    pullRequestBranchName: backstage-integration
  rules:
    - allow: [Component, System, API, Resource, Location]
  locations:
    - type: file
      target: ../../examples/Entities.yaml

    - type: url
      target: https://github.com/Sanjeev-Thiyagarajan/backstage-auth-service/blob/main/catalog-info.yaml

    - type: file
      target: ../../examples/template/template.yaml
      rules:
        - allow: [Template]

Restart the backend. When Backstage imports the entity from GitHub, the Catalog will show the auth-service entry and the provided repository link will be clickable.

A screenshot of a GitHub repository page showing a file list (folders like openapi and src and files such as .gitignore and package.json) with a prompt to add a README. The right sidebar shows repo details and language stats (JavaScript) along with suggested workflows.

Entity updates and refresh behavior

Backstage polls configured locations on a schedule (the default may be tens of minutes). If you change the catalog-info.yaml in GitHub, the Catalog might not reflect the change immediately.
To fetch updates sooner, use the Catalog UI’s refresh action for the entity; this schedules a refresh run for that location.

Example: change the owner in GitHub from guests to auth-team:

apiVersion: backstage.io/v1beta1
kind: Component
metadata:
  name: auth-service
  description: authentication service
  tags:
    - javascript
  links:
    - url: https://google.com
      title: Admin Dashboard
      icon: dashboard
      type: admin-dashboard
spec:
  type: service
  lifecycle: production
  owner: auth-team

If auth-team is not present as a group entity in the Catalog, Backstage will surface a missing-relation warning on the component page. The default Backstage example includes guest and guests entities; here’s the example org.yaml that provides them:

---
apiVersion: backstage.io/v1alpha1
kind: User
metadata:
  name: guest
spec:
  memberOf: [guests]
---
apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
  name: guests
spec:
  type: team
  children: []

If you reference a non-existent owner like auth-team, either add a corresponding group entity or reference an existing group location in app-config.yaml.

Inspecting and unregistering entities

From the Catalog UI you can inspect an entity, view its raw YAML/JSON, and perform actions like unregistering the entity.
Unregistering removes the location Backstage used to import the entity (file or URL).

A screenshot of the Backstage developer portal showing an "auth-service" component page with Overview/About and Relations panels, a warning about missing related entities, and a dropdown menu with actions like "Unregister entity."

Registering via the UI

Alternatively, use the Backstage UI to “Register Existing Component” and paste the URL to your catalog-info.yaml. Backstage will analyze the entity and show what will be imported; you can then import it directly without editing backend config.

A screenshot of the Backstage web UI's "Create a new component" page showing a Templates panel with an "Example Node.js Template" card and a left-hand navigation menu. The page includes search and filter controls and a "Register Existing Component" button.

Templates and repository scanning

Scaffolding templates can create and register catalog-info.yaml automatically when you generate new projects.
Integrations and code-host scanning allow Backstage to discover catalog-info.yaml files across many repositories and import them at scale.

Summary — choosing an approach

Add a local file location in app-config.yaml and restart the backend — useful for demos and local Backstage repo examples.
Add a url location pointing to a remote catalog-info.yaml and restart the backend — recommended for production repositories.
Use the Backstage UI (“Register Existing Component”) to import an entity by URL — convenient for quick imports.
Use templates or repository-scanning integrations to auto-create and register catalog-info.yaml files across many repositories.

After changing app-config.yaml, restart the Backstage backend (or yarn dev when developing) so new locations are picked up. If you update a catalog-info.yaml in a remote repository, use the Catalog’s refresh action to fetch updates sooner than the configured polling interval.

Links and references

Backstage Catalog documentation: https://backstage.io/docs/features/software-catalog/what-is-the-software-catalog
Backstage entity model overview: https://backstage.io/docs/features/software-catalog/descriptor-format
Backstage scaffolder & templates: https://backstage.io/docs/features/software-templates/creating-templates

This completes the demo for registering a component with Backstage.

Introduction

Backstage Basics

Catalog

Templates

TechDocs & Search

Customization & Plugins

Production Backstage

Demo Registering a Component

Where the examples come from

Registering a real component (auth service)

Four common ways to import a component into Backstage

Static import (local file)

Static import (from GitHub)

Entity updates and refresh behavior

Inspecting and unregistering entities

Registering via the UI

Templates and repository scanning

Summary — choosing an approach

Links and references

Watch Video

Practice Lab

​Where the examples come from

​Registering a real component (auth service)

​Four common ways to import a component into Backstage

​Static import (local file)

​Static import (from GitHub)

​Entity updates and refresh behavior

​Inspecting and unregistering entities

​Registering via the UI

​Templates and repository scanning

​Summary — choosing an approach

​Links and references

Watch Video

Practice Lab

Where the examples come from

Registering a real component (auth service)

Four common ways to import a component into Backstage

Static import (local file)

Static import (from GitHub)

Entity updates and refresh behavior

Inspecting and unregistering entities

Registering via the UI

Templates and repository scanning

Summary — choosing an approach

Links and references