Skip to main content

Relationships

The Context Graph has two kinds of edge:

  • A relation connects two entities, for example the service checkout owned by the team payments. The source entity's blueprint defines it.
  • A label association connects an Autoheal resource to an entity, for example the skill release-checks to the service checkout. A label on the resource creates it.

Solid edges are relations. Dashed edges are label associations. The graph view draws them the same way.

Relations​

A blueprint defines the relations its entities can have. Each relation has a key, a target blueprint, and rules:

YAML
relations:
owner:
title: Owner Team
target: team
many: false # one target
required: false
contributors:
title: Contributors
target: person
many: true # a list of targets
schema: # properties stored on each edge
properties:
role:
type: string
title: Role
RuleBehavior
DirectionA relation belongs to its source entity and points to its target. You can traverse it from either end: a team's page lists the services it owns.
One target (many: false)Setting a new target replaces the old one.
Many targets (many: true)Each target is its own edge. Adding a target that is already there changes nothing.
RequiredAn entity cannot be created or updated without a target for this relation.
Target blueprintEach target must be an entity of the target blueprint. A target of another blueprint is refused.
Relation propertiesValues stored on the edge itself, such as a contributor's role. They are checked against the relation's schema.

The system blueprints define these relations:

Custom blueprints can define relations to any blueprint, and system blueprints can be targets. See Custom blueprints.

Where a relation comes from​

Each relation records its origin. A sync replaces only the relations its own source wrote. A relation you set by hand stays when the integration syncs again.

OriginExamplesWritten by
IntegrationA PagerDuty service's escalation team, a GitHub team's members, a ServiceNow CI's owner groupThe sync for that integration, through the resolver
Identity ruleA repository is part_of a service because its service property names that serviceThe resolver
DeclaredAn owner set in the UI, a relation sent through the API or the push API, a depends_on list in a repository's .autoheal/context-graph.yamlPeople and their automation
AgentA dependency an agent found in traces, an owner it inferred from commit historyAgents, through context_graph_write

When two origins disagree about a one-target relation, the field precedence rules pick the winner, the same as for a property.

Unresolved relations​

A relation names its target by the target's canonical name. If no entity of the target blueprint has that name yet, the relation is kept as unresolved:

  • It is stored on the source entity, and the entity response carries the warning SOFT_LINK_UNRESOLVED.
  • It is not drawn as an edge.
  • When an entity with that name appears, the resolver links the relation. You do not need to write it again.

This lets syncs and pushes arrive in any order. A service can name its owner team before the team sync runs.

List unresolved relations with GET /api/v1/context-graph/soft-links. A long-lived unresolved relation usually means a name differs between two tools, for example payments in one and payments-team in the other. Fix it by setting the team's identity, or by changing the name in the source.

Delete an entity that others refer to​

When you delete an entity that other entities refer to, Autoheal lists those entities and asks you to confirm. If you confirm, the relations that pointed to it become unresolved. They resolve again if an entity with the same name returns.

Label associations​

A label connects an Autoheal resource to an entity when:

  1. The label's key is the name of a blueprint in the project, such as service, team, or a custom blueprint such as environment.
  2. The label's value is the canonical name of an entity of that blueprint, such as checkout.

The edge points from the resource to the entity and carries its evidence: the label key and value.

ResourceWhere its labels live
Skilllabels: in its SKILL.md front matter
AgentThe top-level labels: in its agent.yaml
MemoryAutoheal, edited on the memory's page
ArtifactAutoheal, edited on the artifact's page
Integration connectionAutoheal, edited on the integration's page

In files, write each label as one - key: value item. Repeat a key for each value:

YAML
labels:
- team: payments
- service: checkout
- service: ledger
- environment: prod-us

Matching rules:

  • Exact match on the canonical name. The match is case-sensitive. Autoheal stores label keys and values in lowercase, so give an entity a lowercase name if labels must match it. service: checkout matches the service checkout. service: checkout-api does not. Titles are never matched.
  • Label format. A key starts with a lowercase letter and has up to 64 characters: letters, digits, _, -, . and /. A value has 1 to 256 characters.
  • A key that names no blueprint is an ordinary label. priority: high describes the resource and creates no edge.
  • A value that names no entity is a diagnostic. The graph shows it on the resource, and no node is invented. Label editors suggest valid values first.
  • Computed when read. A new entity or blueprint activates existing labels on the next read. Deleting an entity removes the edge but keeps the label.
  • Descriptive only. A label association does not grant access and does not change what an agent runs.
  • Labels on entities do not create edges. Use a relation to connect two entities.

A skill or agent's labels are read from the branch you are viewing, at its latest published commit. A label in a draft does not show until it is published.

The resolver​

The resolver is the reconciliation engine of the Context Graph. It runs each time a source record changes: after a sync, an event, a push, a declared edit, or an agent write. A daily pass checks every link again.

For each source record, it does three things:

Identity rules​

Each blueprint has an ordered list of identity rules. The resolver tries them in order and stops at the first strong match.

BlueprintIdentity rules, in order
person1. Verified email address. 2. Single sign-on identity. 3. A link you make by hand.
team1. A link you make by hand. 2. Normalized name: Payments Team, payments-team and payments match. 3. Similar names become a suggestion.
service1. A declared service name (UI, API, push, or repository file). 2. The service tag or OpenTelemetry service.name that a monitoring tool reports. 3. A repository's service custom property. 4. Similar names become a suggestion.
repositoryProvider, host and repository ID. Never the name, so a renamed repository keeps its identity.
Custom blueprintsThe entity's canonical name.

When a service is renamed, the resolver keeps the old name as an alias. Records that still use the old name keep linking to the same entity.

Integration blueprints without a system counterpart, such as slack_channel and servicenow_cmdb_ci, are their own canonical entities. Each source object is one entity.

Relations inside an integration become graph relations​

Integrations describe relations between their own objects. When both ends are linked to canonical entities, the resolver writes the same relation between those entities:

Integration relationBecomes
pagerduty_service owner → pagerduty_teamservice owner → team
pagerduty_team members → pagerduty_personteam members → person
github_team members → github_personteam members → person
github_repository owner → github_teamrepository owner → team
github_service contributors → github_personservice contributors → person
datadog_service owner → datadog_teamservice owner → team
servicenow_service owner → servicenow_teamservice owner → team
servicenow_team members → servicenow_personteam members → person
slack_team members → slack_personteam members → person
jira_service lead → jira_personservice contributors → person, with role lead

Field precedence​

When several sources supply the same field, the resolver keeps the value from the source with the highest rank for that field:

  1. Declared values: the UI, the API, the push API and repository files.
  2. Integrations, in a default order for each field.
  3. Agents.

Default order between integrations for common fields:

FieldOrder
service.ownerPagerDuty (escalation team) → GitHub (CODEOWNERS team for the repository root) → Datadog (team tag) → ServiceNow (owner group)
service.tierPagerDuty → Datadog → ServiceNow
service.descriptionGitHub → Datadog → PagerDuty → ServiceNow → Jira
person.display_name, person.emailYour organization's users → Slack → PagerDuty → GitHub → Jira → ServiceNow
team.membersAll integrations. Members are combined, not ranked.

Rules:

  • A declared value stays until someone clears it. Syncs and agents never overwrite it.
  • When the top source stops reporting a value, or its record becomes stale, the next source in the order takes over.
  • A many relation, such as members or depends_on, combines the targets from every source. Removing a target in one source removes only that source's edge.
  • The entity's Sources tab shows each field's value from every source, and which one won.

The review queue​

The resolver does not guess. When a decision is uncertain, it creates a suggestion and leaves the graph as it is until a person decides.

SuggestionExampleAccept does
LinkPagerDuty's Checkout API and the service checkout look like the same service: similar name, same owner team, no shared key.Links the record to the entity. The two become one entity.
FieldAn agent found the owner of checkout is platform, but PagerDuty says payments.Sets the agent's value as declared.
RelationAn agent found that checkout calls fraud-score in 92% of traces.Adds the relation as declared.

Open Context Graph → Review to see pending suggestions. You need permission to edit entities to accept or reject one. A rejected suggestion is not raised again for the same records.

You can also list and answer suggestions through the API.