Enforce Lifecycle Set using data collected by Backstage Collector. Automatically check repository and ownership standards on every PR.
How Backstage Collector Powers This Guardrail
The Backstage Collector gathers metadata from your service catalog systems. This data flows into Lunar's Component JSON, where the Lifecycle Set guardrail evaluates it against your standards.
When enabled, this check runs automatically on every PR and in AI coding workflows, providing real-time enforcement with actionable feedback.
Quick Start Configuration
Add both the collector and policy to your lunar-config.yml to enable this guardrail.
# Step 1: Enable the Backstage Collector
collectors:
- uses: github://earthly/lunar-lib/collectors/backstage@v1.0.5
# with: ...
# Step 2: Enable the Backstage Guardrails
policies:
- uses: github://earthly/lunar-lib/policies/backstage@v1.0.5
include: [lifecycle-set]
# with: ...What Backstage Collector Collects
This collector gathers the following data that the Lifecycle Set guardrail evaluates.
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). A file may declare multiple entities
separated by --- (e.g. a Component plus the APIs it provides); every
entity is parsed and recorded under .catalog.native.backstage.entities[],
while the primary entity (the first Component, else the first document) is
hoisted to the top level so the single-entity policies keep working.
Annotations are preserved verbatim with their backstage.io/ or vendor
prefixes. Lints every entity for schema/syntax issues and writes the
aggregated findings to .catalog.native.backstage.valid and
.catalog.native.backstage.errors[].
When backstage_url is configured, it additionally performs a
referential-integrity check: for each grouping reference declared in the
file (spec.domain, spec.system) it queries the Backstage catalog API
(GET <api_path_prefix>/catalog/entities/by-name/<kind>/<namespace>/<name>,
where api_path_prefix defaults to /api; set ref_lookup: by-query to
resolve via the /catalog/entities/by-query search endpoint instead, for
an instance that only authorizes that one) and
records the outcome under .catalog.native.backstage.refs. Whenever
backstage_url is set the collector writes .refs.checked: true as the
"referential integrity ran" signal, plus a per-reference entry: a
definitive lookup records .refs.<kind> = {name, exists} (exists: true
on a 200, false on a 404), while a transient failure (timeout/5xx)
records .refs.<kind> = {name, error} so an outage stays distinguishable
from a real miss. Because a Component has no domain of its own in the
Backstage model — domain membership belongs to its System — a confirmed
spec.system is followed one hop further: that System's own spec.domain
is resolved and recorded at .refs.system_domain = {name, exists, via_system}, which is what makes the domain check meaningful for an
ordinary kind: Component file. The hop reuses the System entity the
system lookup already returned, so it costs one extra request and only
when the system both resolves and declares a domain. The <namespace> is derived from the reference itself —
a qualified ref (ns/name) carries its own, otherwise the component's own
metadata.namespace is used, falling back to default — so no namespace
configuration is required. When backstage_url is empty (the default) no
lookups run and .refs is not written at all — behavior is identical to
today, and the policy's referential-integrity checks skip (pass) rather
than fail.
Those lookups authenticate per auth_mode: a BACKSTAGE_TOKEN bearer
header (default), or AWS SigV4 signing (auth_mode: sigv4) for a
Backstage API fronted by AWS IAM auth, which rejects bearer tokens. An
auth or credential-resolution failure never discards the parse and lint
results — it is recorded as a per-reference {name, error} exactly like
any other non-definitive lookup.
Example Data Flow
Here's an example of the data that Backstage Collector writes to the Component JSON, which Lifecycle Set then evaluates.
{
"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",
"domain": "payments",
"system": "payment-platform",
"providesApis": ["payment-api-grpc"],
"consumesApis": ["user-api", "notification-api"],
"dependsOn": ["resource:database-payments", "resource:cache-redis"]
},
"entities": [
{
"valid": true,
"errors": [],
"apiVersion": "backstage.io/v1alpha1",
"kind": "Component",
"metadata": {
"name": "payment-api",
"description": "Payment processing API",
"annotations": {
"backstage.io/techdocs-ref": "dir:.",
"backstage.io/source-location": "url:https://github.com/acme/payment-api"
},
"tags": ["payments", "api", "tier1"]
},
"spec": {
"type": "service",
"owner": "team-payments",
"lifecycle": "production",
"domain": "payments",
"system": "payment-platform",
"providesApis": ["payment-api-grpc"],
"consumesApis": ["user-api", "notification-api"],
"dependsOn": ["resource:database-payments", "resource:cache-redis"]
}
},
{
"valid": true,
"errors": [],
"apiVersion": "backstage.io/v1alpha1",
"kind": "API",
"metadata": { "name": "payment-api-grpc" },
"spec": {
"type": "grpc",
"owner": "team-payments",
"lifecycle": "production"
}
}
],
"refs": {
"checked": true,
"domain": { "name": "payments", "exists": true },
"system": { "name": "payment-platform", "exists": true }
}
}
}
}
}Configuration Options
Backstage Collector 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) |
backstage_url |
Required | — | Base URL of the Backstage instance (e.g. https://backstage.example.com). When set, the collector cross-checks each declared spec.domain and spec.system against the Backstage catalog API and records the result under `.catalog.native.backstage.refs`. Empty (the default) disables referential-integrity lookups — the collector only parses and lints the local file, exactly as before. |
api_path_prefix |
Optional |
/api
|
Path prefix prepended before `/catalog/entities` when calling the Backstage catalog API. Defaults to `/api`, matching the standard Backstage layout (`<backstage_url>/api/catalog/entities`). Set to an empty string (`""`) when the catalog API is mounted at the root — e.g. behind an API gateway that already strips the `/api` hop, where `<backstage_url>/catalog/entities` is the live endpoint and `/api/catalog/entities` returns 403/404. A leading slash is optional and any trailing slash is ignored (`api`, `/api`, `/api/` are equivalent). Especially relevant with `auth_mode: sigv4`: an IAM-fronted Backstage is usually behind Amazon API Gateway, which is exactly the deployment shape that strips the `/api` hop — so a correct SigV4 setup can still 403 on every lookup if this is left at the default. |
auth_mode |
Optional |
bearer
|
How the collector authenticates to the Backstage catalog API. Only consulted when `backstage_url` is set. - `bearer` — send `Authorization: Bearer <BACKSTAGE_TOKEN>`. Default; unchanged behavior. - `sigv4` — sign every request with AWS Signature V4, for a Backstage API fronted by AWS IAM auth (typically Amazon API Gateway), which rejects Bearer tokens outright. Credentials are resolved at runtime from the standard AWS credential chain — IRSA (EKS), EKS Pod Identity / ECS task role, or EC2 instance profile — so they **auto-refresh and are never supplied by hand**. See the README "AWS SigV4 Authentication" section for the (one-time) IAM-role setup. |
aws_region |
Required | — | AWS region used to scope the SigV4 signature and to reach STS when assuming a web-identity (IRSA) role. Required when `auth_mode: sigv4`, unless `AWS_REGION` is already present in the snippet pod's environment (IRSA and most AWS runtimes set it, but not always). If `auth_mode: sigv4` and neither this input nor the `AWS_REGION` env var is set, the referential-integrity lookups are skipped and each declared reference records an `aws_region required for sigv4` error, rather than signing with an empty region (which would surface as an opaque downstream AWS error). Parsing and linting still run. Ignored for `auth_mode: bearer`. |
aws_service |
Optional |
execute-api
|
AWS service name for the SigV4 signature scope. For a Backstage API behind Amazon API Gateway this is `execute-api` (the default). Override only for other fronting (e.g. a Lambda function URL signs as `lambda`). Ignored for `auth_mode: bearer`. |
ref_lookup |
Optional |
by-name
|
Which catalog endpoint resolves each declared reference. Only consulted when `backstage_url` is set. Both modes produce an identical `.refs` shape, so switching requires no policy changes. - `by-name` — `GET <api_path_prefix>/catalog/entities/by-name/<kind>/<namespace>/<name>`. A direct key lookup whose HTTP status is the answer: 200 = exists, 404 = miss. Default; unchanged behavior. - `by-query` — `GET <api_path_prefix>/catalog/entities/by-query?limit=1&filter=kind=<kind>,metadata.namespace=<namespace>,metadata.name=<name>`. A catalog search, so existence comes from the body rather than the status: a 200 whose `items` array is non-empty = exists, an empty array = miss. Set this when the instance only authorizes the search endpoint — a gateway in front of Backstage can expose `by-query` while rejecting `by-name` outright, in which case every lookup fails however correct the auth is, and the resulting errors read as an outage rather than a misconfiguration. It is the same endpoint the Backstage *cataloger* uses, so an instance the cataloger can already read supports it. |
Backstage Guardrails Inputs
| Input | Required | Default | Description |
|---|---|---|---|
required_annotations |
Required | — | Annotation keys that must be present (and non-empty) in catalog-info.yaml `metadata.annotations`. Two forms are accepted. Comma-separated keys (presence-only, unchanged), e.g. `backstage.io/source-location,pagerduty.com/integration-key`. Or a YAML list, where each entry is either a bare key (presence-only) or a mapping with a `key` and optional value constraints: `type` (string|integer|number|boolean, default string), `min`/`max` (integer/number bounds), `min_length`/`max_length` (string length), `pattern` (full-match regex), and `enum` (allowed values). For example, a `key: example.com/service-tier` with `type: integer`, `min: 0`, `max: 5` requires that annotation to parse as an integer in 0–5. Annotation values are strings in Backstage, so `type` validates that the value *parses* as the declared type (`"2"` satisfies `integer`, `"2.5"` does not). `enum` inherits `type`: its entries are coerced to the declared type before comparison, so `type: integer` with `enum: [1,2,3]` compares integers while the default `type: string` compares strings. Constraints must match the declared type (`min`/`max` for integer/number; `min_length`/`max_length`/`pattern` for string). A value that violates a constraint fails the check; a malformed constraint (unknown type, min greater than max, invalid regex, a constraint on the wrong type, or an enum entry not of the declared type) makes it error. Empty (the default) disables the check. |
required_tag_patterns |
Required | — | Comma-separated list of glob patterns; the component's `metadata.tags` must include at least one tag matching each pattern. Example: `location/*,runs-on/*`. Matching is case-insensitive. Empty (the default) disables the `required-tag-patterns` check. |
disallowed_annotations |
Required | — | Comma-separated list of annotation keys that must NOT be present in catalog-info.yaml `metadata.annotations`. Example: `backstage.io/skip-checks`. Empty (the default) disables the `disallowed-annotations` check. |
disallowed_tag_patterns |
Required | — | Comma-separated list of glob patterns; the component's `metadata.tags` must NOT include any tag matching these patterns. Example: `deprecated/*,internal-only`. Matching is case-insensitive. Empty (the default) disables the `disallowed-tag-patterns` check. |
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 200+ built-in guardrails.
AI agent rules & prompt files
Post-mortem action items
Security & compliance policies
Testing & quality requirements