This tutorial will show you how to add components such as services or websites to the Backstage catalog.
You must have installed the Github App in order to import components. If you have not done this you can find the steps to do this here.
Each component that Backstage tracks must be represented by a YAML file which describes it.
- This YAML file must be called ‘catalog-info.yaml’
- This file must be located in the main branch of the repo of the component that you want to import into Backstage.
The basic structure that you should use for your YAML files looks like this:
apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: sample-service-1 description: | A service for testing Backstage functionality. Configured for GitHub Actions. annotations: github.com/project-slug: roadiehq/sample-service spec: type: service owner: my-team-name lifecycle: production
Best Practice Tip! Ensure the name of the component will make sense to you and your team. This is how other users will refer to your component in Backstage.
Backstage scans your Github Org for new updates periodically, discovers YAML files and adds components automatically. Once you have added a YAML file to any repo that you want to be imported to Backstage it will be found and autopopulated as a component.
If you don’t want to wait for a component to be discovered you can add components manually to Backstage by using the catalog importer available at
/catalog-import. You can do this by copying and pasting the URL of the YAML file into the importer (see video below). If you are just getting started with Backstage we recommend adding your first few files manually as it will get you going quicker.
Click the Home link in the Backstage sidebar to go back to the catalog where you should see your component. Depending on the type of component you imported, you might have to cycle through the tabs until you see your component.
Component Not Appearing?
If your component is not appearing make sure Backstage has permissions to read the repo that you added the yaml file to.
You can check this by going to the Github settings of a repo that Backstage already has access to, then follow
Settings>Integrations>Configure, and making sure your repo is listed in the allowed repos:
Let’s add some documentation for the component we just created so that others in your organization can easily learn how to use it.