GitHub Org Cataloger

Catalogs all repositories from a GitHub organization as Lunar components.

Overview

This cataloger syncs repositories from a GitHub organization into the Lunar catalog. It maps GitHub topics to Lunar tags (with a configurable prefix), supports filtering by visibility and repository name patterns, and can optionally stamp a default owner and domain on all components. It works against github.com as well as GitHub Enterprise Server (via the github_host input).

Synced Data

This cataloger writes to the following Catalog JSON paths:

{
  "components": {
    "github.com/acme/api": {
      "owner": "platform-team@acme.com",
      "tags": ["gh-backend", "gh-go", "gh-production"],
      "meta": {
        "description": "Main API service",
        "visibility": "private",
        "archived": "false"
      }
    },
    "github.com/acme/frontend": {
      "owner": "platform-team@acme.com",
      "tags": ["gh-frontend", "gh-typescript"],
      "meta": {
        "description": "Web application",
        "visibility": "private",
        "archived": "false"
      }
    },
    "github.com/acme/docs": {
      "tags": ["gh-documentation"],
      "meta": {
        "description": "Public documentation site",
        "visibility": "public",
        "archived": "false"
      }
    }
  }
}

Catalogers

This plugin provides the following catalogers:

Hook Type

Installation

Add to your lunar-config.yml:

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

Advanced Configuration

catalogers:
  - uses: github.com/earthly/lunar-lib/catalogers/github-org@v1.0.0
    with:
      org_name: "acme-corp"
      include_public: "true"
      include_private: "true"
      include_internal: "false"
      include_archived: "false"
      exclude_repos: "sandbox-*,deprecated-*,*-archive"
      tag_prefix: "gh-"
      default_owner: "platform-team@acme.com"
      default_domain: "platform"

When default_domain is set, every discovered component gets that domain on its .domain field, and the domain is registered under .domains so the catalog passes the hub's domain-reference validation. A domain definition in lunar-config.yml (or a later cataloger) takes precedence on merge, so you can set a richer description/owner there and this cataloger won't clobber it.

GitHub Enterprise Server

To catalog from a self-hosted GitHub Enterprise Server instead of github.com, set github_host to your GHE hostname:

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

A full URL (e.g. https://github.acme.com) is also accepted — the scheme and any trailing path are stripped automatically. Authentication for a GHE host uses LUNAR_SECRET_GH_ENTERPRISE_TOKEN (routed to the GitHub CLI as GH_ENTERPRISE_TOKEN), falling back to LUNAR_SECRET_GH_TOKEN if that secret is not set — so a github.com and a GHE server can use distinct credentials. Component IDs reflect the host, so a repo on GHE is keyed as github.acme.com/<org>/<repo>.

Include Only Specific Repos

catalogers:
  - uses: github.com/earthly/lunar-lib/catalogers/github-org@v1.0.0
    with:
      org_name: "acme-corp"
      include_repos: "api-*,backend-*,frontend-*"

Source System

This cataloger uses the GitHub CLI (gh) to query the GitHub API. It requires:

1. GitHub CLI installed and available in the container (included in custom image)

2. Authentication via LUNAR_SECRET_GH_TOKEN (same as other GitHub collectors) with appropriate scopes:

   • repo scope for private/internal repositories
   • read:org scope for public repositories only

   For GitHub Enterprise Server (github_host other than github.com) the cataloger reads LUNAR_SECRET_GH_ENTERPRISE_TOKEN and routes it to the GitHub CLI as GH_ENTERPRISE_TOKEN. If that secret is unset it falls back to LUNAR_SECRET_GH_TOKEN, so existing single-token setups keep working.

The cataloger makes API calls to list repositories and their topics. For large organizations, it fetches up to 10,000 repositories per visibility level.