How To Add a Catalog File#

This How-to will walk you through the process of adding a catalog-info.yaml file to your repository so that it is properly cataloged in the Open edX instance of Backstage.

To learn more about why we use catalog-info.yaml and backstage, see OEP-55 Decision 1.


This How-to assumes the following:

  • You know how to use Git and GitHub PR Workflows.

  • You know how to edit YAML files.

  • You have a local clone of the repository you wish to add a catalog file to.

  • You have access to Backstage.


  1. Go to your local clone of the repository you want to update.

  2. Create a catalog-info.yaml file at the root of the repository.

  3. Add the content from sample file from OEP-55 Decision 1

  4. Update the content using the comments as a guide.

  5. Make a pull request with the changes and get it merged into your project.

  6. After the PR has merged, it can take up to 90 minutes for backstage to pick up the changes. But after that time you should see a catalog entry in backstage for your repository.