Skip to main content

Read a component's README

The README card shows, on the overview of a component, the README at the root of its repository. You read how to install and run the component without leaving Astrolabe.

Before you start​

  • The Tech stack plugin is on: the README card comes with it. An administrator turns it on in Administration › Plugins: see Turn on a plugin.
  • The component is in the catalog and points at its repository. The repository host has an integration in Administration › Company connections.

📖 Open the card​

  1. In the top bar, click Catalog.

  2. In the list, click the name of your component, for example my-web-app.

  3. The Overview tab opens. The README card is under the About card.

  4. The card shows the README of the default branch, for example main. Links and images of the README open on the repository host.

  5. To read the file on the host, click Open in the repository, at the top right of the card.

🔎 Which file the card shows​

The card reads the root of the repository, on its default branch, and shows the first file it finds among README.md, README.rst, README.txt and README. A README.md is shown formatted; the others are shown as they are written.

A very long README is cut. The card then says This README is longer than the card can show: open it in the repository to read the rest.

The card reads the repository with the company's integration, like the catalog. You only see the README of a component you can see in the catalog.

🛠 Troubleshooting​

What you seeWhat to do
No README at the root of the repository. and Looked for README.md, README.rst, README.txt and README on the branch main.Add a README.md at the root of the repository, on its default branch. The card shows it at the next visit.
The repository of this component does not exist on … with Check the backstage.io/source-location annotation of the component: the repository may have been renamed, moved or deleted.Fix the backstage.io/source-location annotation in the catalog-info.yaml of the component, so that it points at the repository.
No README card on the overviewThe component has no backstage.io/source-location annotation pointing at a repository, or the Tech stack plugin is off.

✅ That's it!

Next: Common problems with the Tech stack.