> ## Documentation Index > Fetch the complete documentation index at: https://docs.sureops.ai/llms.txt > Use this file to discover all available pages before exploring further. # services.yaml Reference > Field-by-field reference for the sureops service catalog contract. `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 ```yaml theme={null} # .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//` 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. ```yaml theme={null} 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. ```yaml theme={null} 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. ```yaml theme={null} 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. ```yaml theme={null} 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). ```yaml theme={null} deploy: kind: helm # 'helm' | 'kustomize' | 'argocd-app' component_path: components.payments ``` *** ## Complete example ```yaml theme={null} # .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): 1. `src_path` you declared on the service (most specific) 2. The service `name` as a directory hint 3. `src/` and `/` variants 4. 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](https://backstage.io/docs/features/software-catalog/descriptor-format). 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: ```yaml theme={null} 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 `/` 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.