services.yaml Reference

services.yaml is the customer-authoritative service catalog. Agents use it to know who owns each service, what tier it is, how it depends on other services, and where the runbook lives. Authoring it is optional — sureops will discover services from your telemetry without it — but agents are significantly more useful with it.

Minimum viable contract

# .sureops/services.yaml
services:
  - name: payment
    repo: github.com/acme/payment
    owner: payments-team
    runbook: https://wiki.acme.com/runbooks/payment
    tier: P1
    dependsOn: [checkout, currency]

Five fields per service. Everything else is optional.

Field reference

Core fields

Field	Required	Description
`name`	yes	Matches your OTel `resource.service.name`. Agents key everything off this value. Must match the name your services emit.
`repo`	recommended	Where fix-PRs open. Format: `github.com/<org>/<repo>` or full HTTPS URL.
`owner`	recommended	Team or individual who owns this service. Auto-derived from CODEOWNERS if omitted. Used for incident routing and on-call lookup.
`runbook`	recommended	URL or repo-relative path (`./runbooks/payment.md`). Agents include this as grounding context when answering questions about the service.
`tier`	recommended	`P1`, `P2`, or `P3`. Used for severity weighting during triage.
`dependsOn`	recommended	Flat list of service names this service calls. sureops also discovers dependencies from telemetry — your declaration overrides on conflict.
`description`	optional	Free text. Useful for agent grounding but not used for routing.
`type`	optional	Defaults to `service`. Backstage-compatible values accepted: `website`, `library`, etc.
`lifecycle`	optional	`production`, `experimental`, or `deprecated`. Defaults to `production`.

Extended fields (optional, additive)

These fields give agents richer context for fix-PR generation and blast-radius analysis. Teams with the simpler flat schema above continue to parse correctly — unknown nested keys produce warnings, not errors.

`identifiers` — cross-source aliases

Helps sureops match your contract entry with telemetry signals from different sources.

identifiers:
  otel_service_name: payments      # defaults to `name` if omitted
  k8s_label_selector: app.kubernetes.io/component=payments
  k8s_namespace: prod-payments
  k8s_deployment_name: payments-deployment

`image` — container image metadata

Used by the Fix-PR Agent to generate accurate rollback and redeployment actions.

image:
  registry: ghcr.io
  repository_template: "acme/payments"
  default_tag: 1.0.0
  chart_value_path: components.payments.image

`source` — source code metadata

Used by the Fix-PR Agent to locate the relevant code path.

source:
  repo: acme/payments-service    # falls back to top-level `repo` when absent
  src_path: src/payments/
  language: go

`owners` — structured ownership

Richer ownership metadata for routing review requests.

owners:
  team: payments-team            # human-readable
  github_team: payments-oncall   # GitHub slug for review-request routing

`deploy` — deployment mechanism

Used to determine how to apply a fix (Helm rollback vs. Kustomize vs. ArgoCD).

deploy:
  kind: helm                     # 'helm' | 'kustomize' | 'argocd-app'
  component_path: components.payments

Complete example

# .sureops/services.yaml
version: 1

services:
  - name: payments
    repo: github.com/acme/payments-service
    owner: payments-team
    runbook: .sureops/runbooks/payments.md
    tier: P1
    description: "Customer payment processing service"
    dependsOn: [auth, inventory]

    identifiers:
      otel_service_name: payments
      k8s_namespace: prod-payments
      k8s_deployment_name: payments-deployment

    image:
      registry: ghcr.io
      repository_template: "acme/payments"
      default_tag: 1.0.0

    source:
      src_path: src/payments/
      language: go

    owners:
      team: payments-team
      github_team: payments-oncall

    deploy:
      kind: helm
      component_path: components.payments

  - name: auth
    repo: github.com/acme/auth
    owner: platform-team
    runbook: .sureops/runbooks/auth.md
    tier: P1
    dependsOn: [users-db]

  - name: inventory
    repo: github.com/acme/inventory
    owner: catalog-team
    runbook: .sureops/runbooks/inventory.md
    tier: P2
    dependsOn: [products-db]

Owner auto-derivation from CODEOWNERS

If you omit owner for a service, sureops looks up the repository’s CODEOWNERS file and uses the team that owns the service’s source path. File locations checked (first match wins): .github/CODEOWNERS, CODEOWNERS, docs/CODEOWNERS. Match strategy (per service, in order):

src_path you declared on the service (most specific)
The service name as a directory hint
src/<name> and <name>/ variants
Catch-all (* rule, if any)

The owned_by edge in the service topology carries source: "explicit" (you declared it) or source: "codeowners" (derived), so the UI and agents can show which is which.

Backstage compatibility

All core field names are taken from the Backstage entity model. If you adopt Backstage later, you can wrap your existing entries in a Backstage kind: Component envelope. sureops also accepts the full Backstage shape directly:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment
  description: "Payment processing service"
  annotations:
    sureops.ai/runbook: https://wiki.acme.com/runbooks/payment
  labels:
    tier: P1
spec:
  type: service
  lifecycle: production
  owner: payments-team
  dependsOn:
    - component:checkout
    - component:currency

Both shapes produce the same service topology in sureops. Teams already running Backstage can point both tools at the same catalog-info.yaml.

Conflict resolution with auto-discovery

sureops discovers services from your telemetry (OTel service names, Kubernetes labels) and merges that data with your contract. Your contract always wins for any field you declared. Auto-discovery only fills in fields you didn’t specify. Provenance ranking (highest wins): manual > customer_contract > telemetry > kubernetes_scan. In practice: declare what you care about (ownership, runbook, tier). You don’t need to declare fields telemetry already provides (image tags, replica counts, namespace).

Validation rules

name must match OTel service name format: lowercase letters, digits, and hyphens; must start with a letter
repo must be in <owner>/<repo> or full URL format
dependsOn references should resolve to other entries in the same file; unknown references produce a warning, not an error
tier must be one of P1, P2, P3
Nested blocks (identifiers, image, source, owners, deploy) must be mappings if present

Validation errors and warnings appear in Settings → Knowledge Base → Last sync after each ingest.

Getting Started

Onboarding & Setup

Using sureops

Operating Modes & Trust

Integrations

Your Rules (.sureops)

AI Agents & Models

Problem Management

Administration

Self-Hosting

Reference

services.yaml Reference

Minimum viable contract

Field reference

Core fields

Extended fields (optional, additive)

`identifiers` — cross-source aliases

`image` — container image metadata

`source` — source code metadata

`owners` — structured ownership

`deploy` — deployment mechanism

Complete example

Owner auto-derivation from CODEOWNERS

Backstage compatibility

Conflict resolution with auto-discovery

Validation rules

​Minimum viable contract

​Field reference

​Core fields

​Extended fields (optional, additive)

​identifiers — cross-source aliases

​image — container image metadata

​source — source code metadata

​owners — structured ownership

​deploy — deployment mechanism

​Complete example

​Owner auto-derivation from CODEOWNERS

​Backstage compatibility

​Conflict resolution with auto-discovery

​Validation rules

Minimum viable contract

Field reference

Core fields

Extended fields (optional, additive)

`identifiers` — cross-source aliases

`image` — container image metadata

`source` — source code metadata

`owners` — structured ownership

`deploy` — deployment mechanism

Complete example

Owner auto-derivation from CODEOWNERS

Backstage compatibility

Conflict resolution with auto-discovery

Validation rules