Import your GitHub repositories

Astrolabe reads the catalog-info.yaml file of the repositories of a GitHub organization and adds them to the catalog.

You set it up once, as an administrator. Then the catalog fills itself every 30 minutes.

Before you start

The catalog reads GitHub with the token of the GitHub integration. Add it first: see GitHub › Add the GitHub integration.

The token needs the repo, read:org and read:user scopes.

🔧 Configure the GitHub provider

1. In the left sidebar, at the bottom, click Administration.

2. Under PLATFORM, click Catalog. The Providers tab opens.

3. On the GitHub card, click Configure.

4. In Organization, enter the organization to read, as in https://github.com/<organization>, for example acme.

5. Leave Host on github.com.

6. At the bottom of the form, tick Import GitHub members and teams.

7. Click Install.

The window Reloading configuration says Please wait while the instance is reloading.... Then the page comes back.

Every field has its ?

Hover the ? next to a field to see what it expects, with an example.

👥 Members and teams

Import GitHub members and teams also imports the members and the teams of the organization. They can then sign in with GitHub and own components: owner: group:github/<team>. Hover the ? next to it to read it. It needs the Organization above: without one, the form refuses with Organization is required. The token needs the read:org and read:user scopes.

To see them, click Catalog in the left sidebar, then the Users or Groups tab.

If the box is not ticked, only repositories are imported: nobody can sign in with GitHub, and the catalog holds no GitHub user. To change it later, click Configure on the GitHub card again, tick or untick the box, and click Update Configuration.

The other fields

Field	What it does
GitHub App ID	Empty: Astrolabe reads with the token.
Host	github.com. For GitHub Enterprise, its domain name, written exactly as in the GitHub integration.
Catalog Path	Where the file sits in each repository. Empty: /catalog-info.yaml. Wildcards allowed: /**/catalog-info.yaml.
Branch	The branch to read. Empty: each repository's default branch.
Repository Regex	Only the repositories whose name matches, for example ^team-.*.
Include Forks	Ticked: forked repositories are imported too.
Include Archived Repositories	Ticked: archived repositories are imported too.
Include Topics	Click Add Include Topics and type a topic: only the repositories with one of these topics.
Exclude Topics	Click Add Exclude Topics and type a topic: the repositories with it are left out.
Visibility	Click Add Visibility: only repositories with these visibilities (public, private, internal). Empty: all.
Validate Locations Exist	Ticked: checks that the file exists before adding it. Slower, but no error for a repository without one.
Repositories Per Page	How many repositories are read per request. Default: 25.

▶️ Run the collection now

You don't want to wait 30 minutes?

1. On Administration › Catalog, find the Catalog collection table.

2. On the GitHub row, click Run the GitHub collection now in the Actions column.

3. Reload the page. State says Done. Detail says how many files were found, for example 3 catalog files found.

Your components are now in Catalog.

✅ That's it!

Next: show the GitHub tab on a component.