This tutorial will show you how to add components such as services or websites to the Backstage catalog.
You must install the GitHub App in order to import components in private repositories. The steps to do this are here.
Create a file called
catalog-info.yaml in the root of your GitHub repo and add the following YAML to it.
Make sure to update the following variables:
<github-org>to the name of your GitHub organization.
<github-repo>to the name of your repo.
<github-username>to your GitHub username.
apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: <github-repo> title: Sample Service # optional, human readable component name description: My first Backstage catalog item. annotations: github.com/project-slug: <github-org>/<github-repo> spec: type: service owner: user:<github-username> lifecycle: experimental
Components can be manually added to Backstage by using the catalog importer available at
To do this, simply copy/paste the URL of the YAML file into the importer (see video below).
To automatically discover
catalog-info.yaml files, you can also set up a location entity. For more information on this, please visit here.
ℹ️ Note: If you are only trialing backstage, we do not recommend setting up the discovery. It is much easier to manually add files through the catalog importer. Feedback is also much faster.
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 docs to the component we just created so that others in your organization can easily learn how to use it.