Backstage Collector
Parses and lints Backstage catalog-info.yaml files. Writes the raw Backstage descriptor (apiVersion, kind, metadata, spec) to .catalog.native.backstage, preserving annotations as-is.
backstage to your lunar-config.yml:uses: github://earthly/lunar-lib/collectors/backstage@v1.0.5
What This Integration Collects
This integration includes 1 collector that gather metadata from your systems.
catalog-info
Scans the repository for a catalog-info.yaml file (configurable paths)
and parses its contents as-is into .catalog.native.backstage
(apiVersion, kind, metadata, spec). Annotations are preserved verbatim
with their backstage.io/ or vendor prefixes. Lints the file for
schema/syntax issues and writes any findings to
.catalog.native.backstage.valid and .catalog.native.backstage.errors[].
How Collectors Fit into Lunar
Lunar watches your code and CI/CD systems to collect SDLC data from config files, test results, IaC, deployment configurations, security scans, and more.
Collectors are the automatic data-gathering layer. They extract structured metadata from your repositories and pipelines, feeding it into Lunar's centralized database where guardrails evaluate it to enforce your engineering standards.
Learn How Lunar Works →Example Collected Data
This collector writes structured metadata to the Component JSON. Here's an example of the data it produces:
{
"catalog": {
"native": {
"backstage": {
"valid": true,
"errors": [],
"path": "catalog-info.yaml",
"apiVersion": "backstage.io/v1alpha1",
"kind": "Component",
"metadata": {
"name": "payment-api",
"description": "Payment processing API",
"annotations": {
"backstage.io/techdocs-ref": "dir:.",
"pagerduty.com/integration-key": "PXXXXXX",
"grafana/dashboard-selector": "https://grafana.example.com/d/abc123",
"backstage.io/source-location": "url:https://github.com/acme/payment-api"
},
"tags": ["payments", "api", "tier1"]
},
"spec": {
"type": "service",
"owner": "team-payments",
"lifecycle": "production",
"system": "payment-platform",
"providesApis": ["payment-api"],
"consumesApis": ["user-api", "notification-api"],
"dependsOn": ["resource:database-payments", "resource:cache-redis"]
}
}
}
}
}Configuration
Configure this collector in your lunar-config.yml.
Inputs
| Input | Required | Default | Description |
|---|---|---|---|
paths
|
Optional |
catalog-info.yaml,catalog-info.yml
|
Comma-separated list of catalog file paths to check (first match wins) |
Documentation
View on GitHubBackstage Collector
Parses and lints Backstage catalog-info.yaml files.
Overview
This collector scans the repository for a Backstage catalog definition file (catalog-info.yaml or catalog-info.yml), parses it, and lints it for schema/syntax issues. The raw Backstage descriptor (apiVersion, kind, metadata, spec) is written to the .catalog.native.backstage Component JSON path as-is — annotations keep their original backstage.io/ or vendor prefixes. The search paths are configurable via the paths input.
Collected Data
When a catalog-info file is found, this collector writes to the following Component JSON paths. When no file is found, the .catalog.native.backstage namespace is not written — absence of the namespace is the signal.
| Path | Type | Description |
|---|---|---|
.catalog.native.backstage.valid |
boolean | Whether the catalog-info file passed lint/schema checks |
.catalog.native.backstage.errors[] |
array | Lint findings (each with line, message, severity) |
.catalog.native.backstage.path |
string | Relative path to the file that was parsed |
.catalog.native.backstage.apiVersion |
string | Backstage API version (e.g. backstage.io/v1alpha1) |
.catalog.native.backstage.kind |
string | Entity kind (e.g. Component, System, API) |
.catalog.native.backstage.metadata |
object | Raw metadata block (name, description, annotations, tags, etc.) |
.catalog.native.backstage.spec |
object | Raw spec block (type, owner, lifecycle, system, providesApis, consumesApis, dependsOn, etc.) |
Collectors
This plugin provides the following collectors (use include to select a subset):
| Collector | Hook Type | Description |
|---|---|---|
catalog-info |
code | Parses and lints catalog-info.yaml; writes parsed metadata and lint results |
Installation
Add to your lunar-config.yml:
collectors:
- uses: github://earthly/lunar-lib/collectors/backstage@v1.0.0
on: ["domain:your-domain"]
# with:
# paths: "catalog-info.yaml,catalog-info.yml" # Customize search paths
Open Source
This collector is open source and available on GitHub. Contribute improvements, report issues, or fork it for your own use.
Common Use Cases
Explore guardrails that use data from Backstage Collector.
Ready to Automate Your Standards?
See how Lunar can turn your AGENTS.md, engineering wiki, compliance docs, or postmortem action items into automated guardrails with our 100+ built-in guardrails.
AI agent rules & prompt files
Post-mortem action items
Security & compliance policies
Testing & quality requirements