creating-backstage-catalog-provider

name

creating-backstage-catalog-provider

description

Use when building a catalog backend module that ingests entities from an external source (e.g. Azure DevOps, internal API, JSON file). Covers both the normal EntityProvider and the IncrementalEntityProvider for large-volume sources, plus module wiring via catalogProcessingExtensionPoint or incrementalIngestionProvidersExtensionPoint. Triggers on phrases like "catalog provider", "ingest entities from X", "import entities from <source>", or "incremental ingestion".

Creating a Backstage Catalog Provider

When to use this skill

• Building a module that ingests catalog entities from an external source (Azure DevOps, GitHub topic search, internal asset registry, JSON file, etc.)
• Editing an existing catalog-backend-module-* plugin
• The ingestion runs periodically (provider model) — for one-shot processing of an entity definition file, write a CatalogProcessor instead

What you build

A catalog provider is a backend module (createBackendModule({ pluginId: 'catalog', ... })) that registers a provider against an extension point. There are two provider models — pick based on data volume.

Choose the model first: normal vs incremental

Use normal EntityProvider when...	Use IncrementalEntityProvider when...
Total entity count is small (~hundreds at most)	Total entity count is large (thousands+)
The full set fits in memory comfortably	Holding the full set in memory is impractical
The source returns the full snapshot in one round-trip (or a handful)	The source supports pagination — cursor / page-token / offset / etc.
You're prototyping or building a POC