Skip to content
Componecat Docs

Catalog as code

The catalog is most accurate when it lives next to the code it describes. Instead of maintaining entities by hand, teams commit a componecat.yaml file to their repository, and Componecat ingests it — automatically, and continuously.

This is the recommended way to populate the catalog at scale: each team owns its own entries, and the catalog updates itself as the code changes.

The descriptor file

Section titled “The descriptor file”

A descriptor declares one or more entities. At its simplest:

apiVersion: componecat/v1
kind: component
metadata:
  name: payment-gateway
  namespace: payments
  description: Processes card transactions
  owner: team-payments
  tags: [payments, pci, critical]
spec:
  lifecycle: production
  fields:
    languages: [go, protobuf]
  interfaces:
    - kind: api
      name: Payment API
      protocol: grpc
      url: grpc://payments.internal:443
  relationships:
    - kind: depends-on
      target: resource://datastores/payments-db

For every field the descriptor accepts, see the descriptor file reference.

How descriptors are discovered

Section titled “How descriptors are discovered”

Componecat finds and ingests descriptors three ways:

  • On push (webhook). Once your Git provider’s webhook points at Componecat, a push that touches a componecat.yaml re-ingests it in near real time. This is how edits to a descriptor reach the catalog.
  • On a schedule (scan). A periodic scan crawls your configured organizations and repositories and ingests descriptors the catalog doesn’t know about yet, so a new repository is picked up without anyone wiring anything.
  • Manually. You can always create entities directly in the UI or through the APIs. Manually created entities are marked as such and are never overwritten by descriptor sync.

Both automatic paths run off a Git integration. See Repository scanning for connecting one, choosing the scan schedule and file pattern, and wiring up the webhook.

Monorepos

Section titled “Monorepos”

One repository can declare many entities. Place a componecat.yaml at each relevant path (at any depth), and Componecat ingests each independently — a push that touches several of them enqueues one ingestion per file, and scheduled scans fan out the same way.

Ingestion is independent per descriptor: a mistake in one file doesn’t block the others. And a descriptor can reference an entity that a sibling descriptor in the same push defines — the ordering doesn’t matter. If a relationship’s target doesn’t exist yet, Componecat records it and completes it automatically once the target is ingested. An as-yet-unresolved target is surfaced as a warning, never a hard failure.

When descriptor and manual edits collide

Section titled “When descriptor and manual edits collide”

If the same entity is changed both by descriptor sync and by a manual edit, a per-entity conflict strategy decides the outcome: the descriptor wins, the manual change wins, or the conflict is queued as a pending change for someone to review.

Section titled “Related”