Backstage catalog-info.yaml Cataloger

Augments existing Lunar components with metadata read from each repo's catalog-info.yaml, fetched directly via the GitHub Contents API.

Overview

Augments existing Lunar components with owner, domain, and tag metadata from each repo's catalog-info.yaml. Runs per component via the component-cron hook, fetches the file directly from the component's GitHub repo via the Contents API, picks the matching Component entity, and writes owner / domain / tags to that component's catalog entry.

Because component-cron cannot create new components, pair this with a component-defining cataloger — typically github-org.

Synced Data

This cataloger writes to the following Catalog JSON paths on each run:

This cataloger does not define new components — that's out of scope for component-cron. Pair with a component-defining cataloger (see Layering). Domain entries are written as stubs only; for a richer global domain catalog, layer with the backstage cataloger.

{
  "components": {
    "github.com/acme/payment-api": {
      "owner": "group:default/team-payments",
      "domain": "platform.payments",
      "tags": ["bs-payments", "bs-tier1", "bs-type-service", "bs-lifecycle-production"]
    },
    "github.com/acme/web-app": {
      "owner": "group:default/team-web",
      "domain": "platform.frontend",
      "tags": ["bs-frontend", "bs-type-website", "bs-lifecycle-production"]
    }
  },
  "domains": {
    "platform.payments": {
      "description": "Payments platform — billing, ledger, settlement",
      "owner": "group:default/team-payments"
    },
    "platform.frontend": {}
  }
}

Catalogers

Hook Type

component-cron invokes the cataloger separately for each Lunar component currently in the catalog, exposing the component identifier as $LUNAR_COMPONENT_ID. See the cataloger-hooks reference for the full contract.

Daily at 03:00 is a conservative default — catalog-info.yaml changes typically land on the order of hours-to-days, and the schedule is offset by an hour from the standard 0 2 * * * so it lands after component-defining catalogers populate the catalog. Tighten the cadence by overriding hook.schedule in a fork.

Installation

Add to your lunar-config.yml:

catalogers:
  - uses: github.com/earthly/lunar-lib/catalogers/backstage-catalog-info@v1.0.0

Set the GitHub token used to fetch catalog-info.yaml from each repo:

lunar secret set GH_TOKEN <your-github-token>

The token needs Contents: Read on every repo this cataloger will read (repo scope on a classic PAT; contents: read on a fine-grained PAT or GitHub App installation token). Many lunar-lib plugins reuse the same GH_TOKEN, so if you've already set it for github-org or any of the GitHub-API collectors, this cataloger picks it up automatically.

Because component-cron only augments existing components, a component-defining cataloger must run first (see the Layering section below).

Layering with a Component-Defining Cataloger

component-cron requires components to already exist. Run github-org first so this cataloger has something to augment:

catalogers:
  - uses: github.com/earthly/lunar-lib/catalogers/github-org@v1.0.0
    with:
      org_name: "acme"

  - uses: github.com/earthly/lunar-lib/catalogers/backstage-catalog-info@v1.0.0

Pick This or the Live Backstage Cataloger — Not Both

The data source is the same Backstage metadata; the difference is where you read it from. Pick one based on whether you run a Backstage server:

Running both would write to the same .components keys with the same data via different paths — wasteful and the last-declared cataloger silently wins. Don't layer them; pick the one that matches your Backstage setup.

Mapping Components to Backstage Entities

A catalog-info.yaml may declare more than one entity (monorepos commonly ship a Component + a System in one file, or several Components for sub-packages). The cataloger picks which Component corresponds to the current Lunar component using two rules:

1. Annotation match (preferred). If any Component entity in the file has the configured annotation, only annotated entries participate in matching: the cataloger picks the one whose metadata.annotations[<component_id_annotation>] value, prefixed with component_id_prefix, equals $LUNAR_COMPONENT_ID. Defaults assume the standard github.com/project-slug annotation:

   with:
     component_id_annotation: "github.com/project-slug"  # value: "acme/payment-api"
     component_id_prefix: "github.com/"                    # → "github.com/acme/payment-api"
   

   If no annotated entry matches, the cataloger skips silently — it refuses to guess for a repo that already uses annotations to disambiguate.

2. Single-Component fallback. If no Component entity has the annotation and the file contains exactly one Component, that entity is used. This covers the common single-Component-per-repo case where the annotation isn't worth maintaining.

If the file has multiple Component entities and none are annotated, the cataloger skips silently — the YAML needs annotations to disambiguate.

Restricting Synced Kinds

This cataloger only processes kind: Component entities. Domain, System, API, Resource, User, Group, Location, etc. are ignored — they're either container-level concepts (handled by a global cataloger like backstage) or not Lunar catalog concerns.

Sourcing the Domain from a Custom Annotation

Some orgs model component domains via a custom annotation rather than the canonical Backstage spec.domain field — for example, to express a hierarchical name like engineering.tooling.observability that Backstage's flat spec.domain doesn't model well. Set domain_annotation to that key and the cataloger reads it from metadata.annotations[<key>]:

catalogers:
  - uses: github.com/earthly/lunar-lib/catalogers/backstage-catalog-info@v1.0.0
    with:
      domain_annotation: "yourorg.example.com/domain"

When set and the matched Component has that annotation, its value wins over spec.domain / spec.system. When the annotation is absent on a given entity, the cataloger falls back to spec.domain then spec.system as usual. Leave domain_annotation empty (the default) to use only the canonical Backstage fields.

Owner Format

Backstage spec.owner is typically an entity reference like group:default/team-payments or user:default/jane, not an email. By default this cataloger passes the value through verbatim — matching what the existing policies/backstage/owner-set policy already accepts (team-payments, group:infra, user:alice are all valid).

If you'd rather store bare names, set owner_format: bare-name to strip the <kind>:<namespace>/ prefix. default_owner is also written verbatim, regardless of owner_format.

Source System

GitHub — the cataloger calls the Contents API once per component invocation to fetch catalog-info.yaml from each repo. Requirements:

• GH_TOKEN secret with read access to every repo this cataloger will read (Contents: Read on a fine-grained PAT, repo on a classic PAT, or contents: read on a GitHub App installation token).
• Component IDs match <component_id_prefix><owner>/<repo> (default github.com/<owner>/<repo>). Non-GitHub component IDs are skipped silently — this cataloger is GitHub-specific.

The cataloger makes no other external calls. YAML parsing and entity selection happen in-process; the only outbound traffic is the GitHub fetch.