Import your GitLab projects

Astrolabe reads the catalog-info.yaml file of your GitLab projects 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 GitLab with the token of the GitLab integration. Add it first: see GitLab › Add the GitLab integration.

The token needs the read_api and read_repository scopes.

🔧 Configure the GitLab provider

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

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

3. On the GitLab card, click Configure.

4. In Host, pick your GitLab in the list. It is the host of your integration.

5. In Group, enter the group to read, as in https://<host>/<group>. Its subgroups come with it.

   This field also names your teams

   Imported teams are named after their path under this group: with acme, the group acme/paiement/api becomes paiement-api. Components write that name in owner. So pick the top group of your company. See Give a component its GitLab owner.

6. 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.

✏️ Change the group later

1. Open Administration › Catalog, then Configure on the GitLab card.

2. In Group, type the new group. As soon as it differs from the saved one, a warning shows under the field, for example with acme saved and acme/paiement typed:

   The teams already imported will be renamed, and the owner of the components that name them will no longer be found until you update it. Example: acme/paiement/api was paiement-api and becomes api.

3. Click Update Configuration.

4. In each catalog-info.yaml, write the new team name in owner. See Give a component its GitLab owner.

Type the saved group back and the warning goes away.

The other fields

Field	What it does
Only projects I am a member of	Only the projects of the token's user. Recommended on gitlab.com.
Branches	The branches to read, one per row: click Add Branches, type master, click Add Branches again, type backstage. Empty: each project's default branch. No / in a name. Remove takes a branch out.
Catalog File	The file to read at the root of each project. Default: catalog-info.yaml.
Project Regex	Only the projects whose name matches, for example ^team-.*.
Skip Forked Repositories	Leaves out forked projects.
Import GitLab groups and their members	Also imports your groups. See Import your GitLab groups.
Excluded Repositories	Projects to leave out, one path per line, for example acme/sandbox.
Topics	Only the projects that carry one of these GitLab topics, one per line.
Include Archived Repositories	Also imports archived projects.
Fallback Branch	The branch to read when the catalog file is not on a project's default branch.
Use GitLab Search	Finds the projects through GitLab search instead of listing every project in scope.

▶️ Run the collection now

You don't want to wait 30 minutes?

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

2. On the GitLab row, in the Actions column, click the play button (Run the GitLab collection now; once you also import groups, it is Run the GitLab projects collection now).

3. Don't reload the page. State turns to Running, then to Done. Detail says how many files were found, for example 3 catalog files found. The play of the GitLab row starts only that row: see Run a catalog collection now.

The GitLab (groups and users) row, just above, appears once you turned on Import GitLab groups and their members. Its Detail says what came in, for example 3 groups and 1 user imported.

Your components are now in Catalog.

✅ That's it!

To name a real GitLab group as the owner of each component, read Import your GitLab groups.