Backstage Guardrails

✓ Policy Beta Repository And Ownership

Validates Backstage catalog-info.yaml entries for completeness and compliance. Checks that the catalog file exists and is valid, owner is set, lifecycle stage is defined, and system grouping is assigned.

Add backstage to your lunar-config.yml:

uses: github://earthly/lunar-lib/policies/backstage@v1.0.5

Get Started View on GitHub

Included Guardrails

This policy includes 5 guardrails that enforce standards for your repository and ownership.

Guardrail

`catalog-info-exists`

Verifies that a catalog-info.yaml file exists in the repository. Every Backstage-managed service must have a catalog definition file. Fails if the backstage collector reports no catalog file found.

backstage catalog-info service catalog file exists

View Guardrail

Guardrail

`catalog-info-valid`

Verifies that the catalog-info.yaml file is syntactically valid and passes Backstage descriptor schema checks (no lint errors reported by the collector). Fails if the file is missing or has lint errors.

backstage catalog-info lint schema validation

View Guardrail

Guardrail

`owner-set`

Validates that the owner field (spec.owner) is populated in the catalog-info.yaml. Ownership is required for incident routing and accountability. Fails if no catalog file is present.

backstage ownership owner accountability

View Guardrail

Guardrail

`lifecycle-set`

Validates that the lifecycle stage (spec.lifecycle) is defined in the catalog-info.yaml. Lifecycle stages (production, experimental, deprecated) inform operational expectations and SLO requirements. Fails if no catalog file is present.

backstage lifecycle production deprecated

View Guardrail

Guardrail

`system-set`

Validates that the system grouping (spec.system) is defined in the catalog-info.yaml. System assignment enables dependency mapping and architectural visibility. Fails if no catalog file is present.

backstage system grouping architecture

View Guardrail

How Guardrails Fit into Lunar

Lunar guardrails define your engineering standards as code. They evaluate data collected by integrations and produce pass/fail checks with actionable feedback.

Policies support gradual enforcement—from silent scoring to blocking PRs or deployments—letting you roll out standards at your own pace without disrupting existing workflows.

Learn How Lunar Works →

↓ Integrations Gather Data

Collectors extract metadata from code, CI pipelines, tool outputs, and scans

{ } Centralized as JSON

All data merged into each component's unified metadata document

✓ Guardrails Enforce Standards This Policy

Real-time feedback in PRs and AI workflows

Required Integrations

This policy evaluates data gathered by one or more of the following integration(s). Make sure to enable them in your lunar-config.yml.

Collector Service Catalog Required

Backstage Collector

Provides parsed Backstage catalog metadata at .catalog.native.backstage

Documentation

View on GitHub

Backstage Guardrails

Enforce Backstage service catalog standards for catalog-info.yaml completeness.

Overview

Validates that Backstage catalog entries include required metadata for service ownership, lifecycle management, and system architecture. These checks apply to repositories that use Backstage as their service catalog and must be paired with the backstage collector.

Behavior when no catalog file is present: All checks fail. A repository enabled for this policy is expected to be registered in Backstage, so a missing catalog-info.yaml is treated as a policy violation (not a skip).

Policies

This plugin provides the following policies (use include to select a subset):

Policy	Description
`catalog-info-exists`	Verifies catalog-info.yaml exists in the repository
`catalog-info-valid`	Verifies catalog-info.yaml passes lint/schema checks
`owner-set`	Validates that `spec.owner` is populated
`lifecycle-set`	Validates that `spec.lifecycle` is defined
`system-set`	Validates that `spec.system` is defined

Required Data

This policy reads from the following Component JSON paths. The presence of .catalog.native.backstage indicates that a catalog-info file was found; its absence means no file exists.

Path	Type	Provided By
`.catalog.native.backstage`	object	`backstage` collector (namespace present ⇔ file found)
`.catalog.native.backstage.valid`	boolean	`backstage` collector
`.catalog.native.backstage.errors[]`	array	`backstage` collector
`.catalog.native.backstage.spec.owner`	string	`backstage` collector
`.catalog.native.backstage.spec.lifecycle`	string	`backstage` collector
`.catalog.native.backstage.spec.system`	string	`backstage` collector

Note: Ensure the backstage collector is configured before enabling this policy.

Installation

Add to your lunar-config.yml:

policies:
  - uses: github://earthly/lunar-lib/policies/backstage@v1.0.0
    on: ["domain:your-domain"]
    enforcement: report-pr
    # include: [catalog-info-exists, owner-set]  # Only run specific checks

Examples

Passing Example

{
  "catalog": {
    "native": {
      "backstage": {
        "valid": true,
        "errors": [],
        "path": "catalog-info.yaml",
        "apiVersion": "backstage.io/v1alpha1",
        "kind": "Component",
        "metadata": { "name": "payment-api" },
        "spec": {
          "type": "service",
          "owner": "team-payments",
          "lifecycle": "production",
          "system": "payment-platform"
        }
      }
    }
  }
}

Failing Example (spec fields missing)

{
  "catalog": {
    "native": {
      "backstage": {
        "valid": true,
        "errors": [],
        "path": "catalog-info.yaml",
        "apiVersion": "backstage.io/v1alpha1",
        "kind": "Component",
        "metadata": { "name": "payment-api" },
        "spec": {
          "type": "service"
        }
      }
    }
  }
}

Failing Example (no catalog-info.yaml)

{}

The .catalog.native.backstage namespace is simply absent. All five checks fail.

Failure messages:

"No catalog-info.yaml found"
"catalog-info.yaml has lint errors: <details>"
"Owner (spec.owner) is not set in catalog-info.yaml"
"Lifecycle stage (spec.lifecycle) is not set in catalog-info.yaml"
"System (spec.system) is not set in catalog-info.yaml"

Remediation

When this policy fails, resolve it by updating your catalog-info.yaml:

Missing file - Create a catalog-info.yaml in the repository root following the Backstage descriptor format
Lint errors - Review .catalog.native.backstage.errors[] in the component payload and fix the reported issues
Missing owner - Add spec.owner with a valid team or user reference (e.g., team-payments)
Missing lifecycle - Add spec.lifecycle with a stage: production, experimental, or deprecated
Missing system - Add spec.system referencing the parent system that groups related components

Open Source

This policy is open source and available on GitHub. Contribute improvements, report issues, or fork it for your own use.

View Repository

Common Use Cases

Explore how individual guardrails work with specific integrations.

Catalog Info Exists + Backstage Collector Verifies that a catalog-info.yaml file exists in the repository. Every...

→

Catalog Info Valid + Backstage Collector Verifies that the catalog-info.yaml file is syntactically valid and passes...

→

Owner Set + Backstage Collector Validates that the owner field (spec.owner) is populated in...

→

Lifecycle Set + Backstage Collector Validates that the lifecycle stage (spec.lifecycle) is defined in the...

→

System Set + Backstage Collector Validates that the system grouping (spec.system) is defined in the...

→

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.

Works with any process

AI agent rules & prompt files

Post-mortem action items

Security & compliance policies

Testing & quality requirements

Automate Now

Paste your AGENTS.md or manual process doc and get guardrails in minutes

Book a Demo